diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..1d14095 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,11 @@ +# Copilot Instructions + +## Quarto rendering + +Before requesting review on any change to a `.qmd` file: + +1. **Always render the document locally** (`quarto render ` or `quarto preview`) and inspect the HTML output. +2. **Verify that math renders correctly** — open the rendered HTML and confirm MathJax typesetting is visible and correct. +3. **Do not push until rendering succeeds** and the output looks as intended. + +This step is required because MathJax rendering failures are silent in R/knitr output and only visible in the browser. diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml new file mode 100644 index 0000000..6311e45 --- /dev/null +++ b/.github/workflows/preview.yml @@ -0,0 +1,65 @@ +name: Quarto Preview + +on: + pull_request: + types: + - opened + - reopened + - synchronize + - closed + +jobs: + build-deploy: + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Quarto + uses: quarto-dev/quarto-actions/setup@v2 + + - uses: r-lib/actions/setup-r@v2 + with: + use-public-rspm: true + + - uses: r-lib/actions/setup-r-dependencies@v2 + with: + packages: | + any::knitr + any::rmarkdown + any::DT + + - name: Render + uses: quarto-dev/quarto-actions/render@v2 + + - name: Deploy PR Preview + id: preview-step + uses: rossjrw/pr-preview-action@v1 + with: + source-dir: ./_site/ + action: ${{ github.event.action == 'closed' && 'remove' || 'deploy' }} + preview-branch: gh-pages + comment: "false" + + - uses: marocchino/sticky-pull-request-comment@v2 + if: steps.preview-step.outputs.deployment-action == 'deploy' + with: + header: pr-preview + recreate: true + message: | + [PR Preview Action](https://github.com/rossjrw/pr-preview-action) ${{ steps.preview-step.outputs.action-version }} + :---: + :rocket: View preview at ${{ steps.preview-step.outputs.preview-url }} + + - uses: marocchino/sticky-pull-request-comment@v2 + if: steps.preview-step.outputs.deployment-action == 'remove' + with: + header: pr-preview + recreate: true + message: | + [PR Preview Action](https://github.com/rossjrw/pr-preview-action) ${{ steps.preview-step.outputs.action-version }} + :---: + Preview removed because the pull request was closed. diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..662ed29 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,39 @@ +on: + workflow_dispatch: + push: + branches: main + +name: Quarto Publish + +jobs: + build-deploy: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Quarto + uses: quarto-dev/quarto-actions/setup@v2 + + - uses: r-lib/actions/setup-r@v2 + with: + use-public-rspm: true + + - uses: r-lib/actions/setup-r-dependencies@v2 + with: + packages: | + any::knitr + any::rmarkdown + any::DT + + - name: Render + uses: quarto-dev/quarto-actions/render@v2 + + - name: Deploy 🚀 + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: _site/ + clean-exclude: pr-preview/ + force: false diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2f7dfc0 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +/.quarto/ +/_site/ +/_freeze/ +/*.deb diff --git a/_quarto.yml b/_quarto.yml new file mode 100644 index 0000000..9fc539e --- /dev/null +++ b/_quarto.yml @@ -0,0 +1,21 @@ +project: + type: website + +website: + title: "macros" + navbar: + left: + - href: index.qmd + text: Home + - href: macros-table.qmd + text: Macro Reference + +format: + html: + theme: cosmo + toc: true + +execute: + warning: false + message: false + freeze: auto diff --git a/index.qmd b/index.qmd new file mode 100644 index 0000000..d12c535 --- /dev/null +++ b/index.qmd @@ -0,0 +1,76 @@ +--- +title: "macros" +--- + +This repository contains LaTeX macros for mathematical notation used in statistical and regression modeling, originally from the [rme repository](https://github.com/d-morrison/rme). + +## Contents + +- `macros.qmd`: LaTeX macro definitions for use in Quarto documents +- [Macro Reference](macros-table.qmd): Searchable table of all macros + +These macros provide convenient shorthand for common mathematical expressions used in: + +- Probability and statistics +- Regression models (linear, logistic, Poisson, survival analysis) +- Maximum likelihood estimation +- Mathematical notation (vectors, matrices, derivatives, etc.) + +## Using as a Git Submodule + +### Adding the submodule to your project + +From the root of your project repository, run: + +```bash +git submodule add https://github.com/d-morrison/macros.git macros +git commit -m "Add macros submodule" +``` + +This will clone the `macros` repository into a `macros/` subdirectory and record it as a submodule. + +### Cloning a project that already uses this submodule + +When cloning a repository that includes this submodule, initialize and fetch the submodule content with: + +```bash +git clone --recurse-submodules +``` + +Or, if you have already cloned the repository without `--recurse-submodules`: + +```bash +git submodule update --init +``` + +### Updating the submodule + +To pull the latest changes from this repository into your project: + +```bash +git submodule update --remote macros +git commit -m "Update macros submodule" +``` + +### Including the macros in a Quarto document + +In your Quarto document's YAML front matter, reference the `macros.qmd` file using the `include-in-header` or via `_quarto.yml`: + +```yaml +--- +include-in-header: + - macros/macros.qmd +--- +``` + +Or, in a shared `_quarto.yml` configuration file: + +```yaml +format: + html: + include-in-header: + - macros/macros.qmd + pdf: + include-in-header: + - macros/macros.qmd +``` diff --git a/macros-table.qmd b/macros-table.qmd new file mode 100644 index 0000000..479552e --- /dev/null +++ b/macros-table.qmd @@ -0,0 +1,163 @@ +--- +title: "Macro Reference" +--- + +```{r} +#| label: embed-macros +#| echo: false +#| results: asis + +# Embed macro definitions in a hidden Quarto fenced-div so pandoc processes +# the $$ block into a real MathJax display-math element (not raw HTML). +# Raw
...
blocks are passed through by pandoc without math processing. +lines <- readLines("macros.qmd", warn = FALSE) +lines <- lines[!grepl("^\\s*