diff --git a/.Rprofile b/.Rprofile index a2a2e1b..90dc04b 100644 --- a/.Rprofile +++ b/.Rprofile @@ -1,4 +1,4 @@ if (interactive()) { - suppressMessages(require(usethis, quietly = TRUE)) - suppressMessages(require(devtools, quietly = TRUE)) + require(usethis) + require(devtools) } diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index a624806..375a5a8 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -27,6 +27,16 @@ jobs: with: tinytex: true + - 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 + - name: Render uses: quarto-dev/quarto-actions/render@v2 @@ -35,7 +45,7 @@ jobs: - name: Detect changed chapters (based on rendered files) run: python3 .github/scripts/detect-changed-chapters.py env: - HTML_DIR: ./docs + HTML_DIR: ./_site # Set to 'true' if PR has 'no-preview-highlights' label DISABLE_PREVIEW_HIGHLIGHTS: ${{ contains(github.event.pull_request.labels.*.name, 'no-preview-highlights') }} @@ -58,24 +68,24 @@ jobs: echo "${{ env.PREVIEW_CHANGED_CHAPTERS }}" python3 .github/scripts/highlight-html-changes.py env: - HTML_DIR: ./docs + HTML_DIR: ./_site PREVIEW_CHANGED_CHAPTERS: ${{ env.PREVIEW_CHANGED_CHAPTERS }} - name: Create DOCX with tracked changes run: python3 .github/scripts/create-docx-tracked-changes.py env: - DOCX_DIR: ./docs + DOCX_DIR: ./_site - name: Add home page banner run: python3 .github/scripts/add-home-banner.py env: - HTML_DIR: ./docs + HTML_DIR: ./_site PREVIEW_CHANGED_CHAPTERS: ${{ env.PREVIEW_CHANGED_CHAPTERS }} - name: Deploy PR Preview uses: rossjrw/pr-preview-action@main with: - source-dir: ./docs/ + source-dir: ./_site/ # Deploy on label changes too, not just open/reopen/synchronize # The 'auto' action ignores label events, so we explicitly set 'deploy' for non-closed PRs action: ${{ github.event.action == 'closed' && 'remove' || 'deploy' }} diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 35e6b93..e2747f6 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -19,12 +19,22 @@ jobs: with: tinytex: true + - 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 + - name: Render uses: quarto-dev/quarto-actions/render@v2 - name: Deploy πŸš€ uses: JamesIves/github-pages-deploy-action@v4 with: - folder: docs/ + folder: _site/ clean-exclude: pr-preview/ force: false diff --git a/.gitignore b/.gitignore index 77a99df..638adcf 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,8 @@ # Quarto /.quarto/ -/docs/ +/_site/ +/_slides/ +/_handouts/ *.pdf *.docx *.epub diff --git a/DESCRIPTION b/DESCRIPTION index 24f7162..8f8467a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,9 +1,22 @@ -Package: qbt -Type: Book -Title: qbt (Quarto Book Template) -Version: 0.0.1 -Description: A template repository for creating books with Quarto -Maintainer: Your Name -Author: Your Name -Language: en-US +Package: qwt +Title: Quarto Website Template +Version: 0.1.0 +Authors@R: + person("Your Name", email = "your.email@example.com", role = c("aut", "cre")) +Description: A template for creating websites with Quarto. Includes support for + multiple output formats including HTML, DOCX, RevealJS slides, and PDF handouts. +License: MIT + file LICENSE Encoding: UTF-8 +Roxygen: list(markdown = TRUE) +RoxygenNote: 7.3.2 +URL: https://github.com/UCD-SERG/qwt +BugReports: https://github.com/UCD-SERG/qwt/issues +Depends: + R (>= 4.1.0) +Suggests: + knitr, + rmarkdown, + spelling, + usethis, + devtools +VignetteBuilder: knitr diff --git a/LICENSE b/LICENSE index 670154e..5efa473 100644 --- a/LICENSE +++ b/LICENSE @@ -1,116 +1,21 @@ -CC0 1.0 Universal - -Statement of Purpose - -The laws of most jurisdictions throughout the world automatically confer -exclusive Copyright and Related Rights (defined below) upon the creator and -subsequent owner(s) (each and all, an "owner") of an original work of -authorship and/or a database (each, a "Work"). - -Certain owners wish to permanently relinquish those rights to a Work for the -purpose of contributing to a commons of creative, cultural and scientific -works ("Commons") that the public can reliably and without fear of later -claims of infringement build upon, modify, incorporate in other works, reuse -and redistribute as freely as possible in any form whatsoever and for any -purposes, including without limitation commercial purposes. These owners may -contribute to the Commons to promote the ideal of a free culture and the -further production of creative, cultural and scientific works, or to gain -reputation or greater distribution for their Work in part through the use and -efforts of others. - -For these and/or other purposes and motivations, and without any expectation -of additional consideration or compensation, the person associating CC0 with a -Work (the "Affirmer"), to the extent that he or she is an owner of Copyright -and Related Rights in the Work, voluntarily elects to apply CC0 to the Work -and publicly distribute the Work under its terms, with knowledge of his or her -Copyright and Related Rights in the Work and the meaning and intended legal -effect of CC0 on those rights. - -1. Copyright and Related Rights. A Work made available under CC0 may be -protected by copyright and related or neighboring rights ("Copyright and -Related Rights"). Copyright and Related Rights include, but are not limited -to, the following: - - i. the right to reproduce, adapt, distribute, perform, display, communicate, - and translate a Work; - - ii. moral rights retained by the original author(s) and/or performer(s); - - iii. publicity and privacy rights pertaining to a person's image or likeness - depicted in a Work; - - iv. rights protecting against unfair competition in regards to a Work, - subject to the limitations in paragraph 4(a), below; - - v. rights protecting the extraction, dissemination, use and reuse of data in - a Work; - - vi. database rights (such as those arising under Directive 96/9/EC of the - European Parliament and of the Council of 11 March 1996 on the legal - protection of databases, and under any national implementation thereof, - including any amended or successor version of such directive); and - - vii. other similar, equivalent or corresponding rights throughout the world - based on applicable law or treaty, and any national implementations thereof. - -2. Waiver. To the greatest extent permitted by, but not in contravention of, -applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and -unconditionally waives, abandons, and surrenders all of Affirmer's Copyright -and Related Rights and associated claims and causes of action, whether now -known or unknown (including existing as well as future claims and causes of -action), in the Work (i) in all territories worldwide, (ii) for the maximum -duration provided by applicable law or treaty (including future time -extensions), (iii) in any current or future medium and for any number of -copies, and (iv) for any purpose whatsoever, including without limitation -commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes -the Waiver for the benefit of each member of the public at large and to the -detriment of Affirmer's heirs and successors, fully intending that such Waiver -shall not be subject to revocation, rescission, cancellation, termination, or -any other legal or equitable action to disrupt the quiet enjoyment of the Work -by the public as contemplated by Affirmer's express Statement of Purpose. - -3. Public License Fallback. Should any part of the Waiver for any reason be -judged legally invalid or ineffective under applicable law, then the Waiver -shall be preserved to the maximum extent permitted taking into account -Affirmer's express Statement of Purpose. In addition, to the extent the Waiver -is so judged Affirmer hereby grants to each affected person a royalty-free, -non transferable, non sublicensable, non exclusive, irrevocable and -unconditional license to exercise Affirmer's Copyright and Related Rights in -the Work (i) in all territories worldwide, (ii) for the maximum duration -provided by applicable law or treaty (including future time extensions), (iii) -in any current or future medium and for any number of copies, and (iv) for any -purpose whatsoever, including without limitation commercial, advertising or -promotional purposes (the "License"). The License shall be deemed effective as -of the date CC0 was applied by Affirmer to the Work. Should any part of the -License for any reason be judged legally invalid or ineffective under -applicable law, such partial invalidity or ineffectiveness shall not -invalidate the remainder of the License, and in such case Affirmer hereby -affirms that he or she will not (i) exercise any of his or her remaining -Copyright and Related Rights in the Work or (ii) assert any associated claims -and causes of action with respect to the Work, in either case contrary to -Affirmer's express Statement of Purpose. - -4. Limitations and Disclaimers. - - a. No trademark or patent rights held by Affirmer are waived, abandoned, - surrendered, licensed or otherwise affected by this document. - - b. Affirmer offers the Work as-is and makes no representations or warranties - of any kind concerning the Work, express, implied, statutory or otherwise, - including without limitation warranties of title, merchantability, fitness - for a particular purpose, non infringement, or the absence of latent or - other defects, accuracy, or the present or absence of errors, whether or not - discoverable, all to the greatest extent permissible under applicable law. - - c. Affirmer disclaims responsibility for clearing rights of other persons - that may apply to the Work or any use thereof, including without limitation - any person's Copyright and Related Rights in the Work. Further, Affirmer - disclaims responsibility for obtaining any necessary consents, permissions - or other rights required for any use of the Work. - - d. Affirmer understands and acknowledges that Creative Commons is not a - party to this document and has no duty or obligation with respect to this - CC0 or use of the Work. - -For more information, please see - +MIT License + +Copyright (c) 2026 UCD-SERG + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.Rmd b/README.Rmd index 309f7c8..39f54d4 100644 --- a/README.Rmd +++ b/README.Rmd @@ -11,24 +11,24 @@ knitr::opts_chunk$set( ) ``` -# qbt ([Q]{.underline}uarto [B]{.underline}ook [T]{.underline}emplate) +# qwt ([Q]{.underline}uarto [W]{.underline}ebsite [T]{.underline}emplate) -A template repository for creating books with [Quarto](https://quarto.org/). -This template provides everything you need to quickly start writing your own book. +A template repository for creating websites with [Quarto](https://quarto.org/). +This template provides everything you need to quickly start writing your own website. ## Features -- πŸ“š **Book-ready structure** with sample chapters and references +- 🌐 **Website-ready structure** with sample chapters and references - 🎨 **Customizable themes** supporting light and dark modes - πŸš€ **Automatic deployment** to GitHub Pages via GitHub Actions - πŸ”— **Automated link checking** to ensure all URLs are reachable -- πŸ“„ **Multiple output formats** including HTML, PDF, EPUB, and DOCX +- πŸ“„ **Multiple output formats** including HTML, PDF, RevealJS slides, and DOCX - πŸ“‘ **Bibliography support** with BibTeX integration - πŸ”’ **Automatic numbering** of sections and cross-references -- πŸ’… **Custom CSS** for styling your book +- πŸ’… **Custom CSS** for styling your website - πŸ” **PR Preview** with change highlighting for pull requests - βœ… **Automated checks** including spell checking and linting - πŸ€– **GitHub Copilot integration** with custom setup steps @@ -57,49 +57,59 @@ To verify Quarto is installed: quarto --version ``` -### Customize your book +### Customize your website -1. **Edit `_quarto.yml`** to update: - - Book title and author +1. **Edit `_quarto-website.yml`** to update: + + - Website title and site URL - Repository URL - - Chapter list + - Navigation menu items - Theme and styling options -2. **Modify `index.qmd`** to create your book's homepage/introduction +2. **Modify `index.qmd`** to create your website's homepage + +3. **Edit or create pages** (`.qmd` files): -3. **Edit or create chapters** (`.qmd` files): - - Modify `chapter1.qmd` and `chapter2.qmd` as needed - - Create new chapters and add them to the `chapters` list in `_quarto.yml` + - Modify files in the `chapters/` directory as needed + - Create new pages and add them to the navigation menu in `_quarto-website.yml` 4. **Add references** to `references.bib` in BibTeX format 5. **Customize styling** in `styles.css` -## Building the book +## Building the website ### Local preview -To preview your book with live reload during development: +To preview your website with live reload during development: ```bash quarto preview ``` -This will open your book in a web browser and automatically refresh when you make changes. +This will open your website in a web browser and automatically refresh when you make changes. -### Render the book +### Render the website -To render the complete book: +To render the complete website: ```bash quarto render ``` -The output will be generated in the `docs/` directory. +The output will be generated in the `_site/` directory. + +### Multiple output formats + +This template supports multiple output formats through Quarto profiles: + +- **Website** (default): `quarto render` or `quarto render --profile website` +- **RevealJS slides**: `quarto render --profile revealjs` (output in `_slides/`) +- **PDF handouts**: `quarto render --profile handout` (output in `_handouts/`) ## Publishing to GitHub Pages -This template includes a GitHub Actions workflow (`.github/workflows/publish.yml`) that automatically builds and publishes your book to GitHub Pages when you push to the main branch. +This template includes a GitHub Actions workflow (`.github/workflows/publish.yml`) that automatically builds and publishes your website to GitHub Pages when you push to the main branch. ### Setup steps: @@ -110,13 +120,13 @@ This template includes a GitHub Actions workflow (`.github/workflows/publish.yml 2. **Push to main branch**: ```bash git add . - git commit -m "Initial book setup" + git commit -m "Initial website setup" git push origin main ``` 3. **Wait for the workflow** to complete (check the Actions tab) -4. **Access your book** at: `https://YOUR-USERNAME.github.io/YOUR-REPO/` +4. **Access your website** at: `https://YOUR-USERNAME.github.io/YOUR-REPO/` ## GitHub Actions Workflows @@ -124,7 +134,7 @@ This template includes several automated workflows to enhance your development e ### πŸš€ Publish Workflow (`publish.yml`) -Automatically builds and deploys your book to GitHub Pages when you push to the main branch. +Automatically builds and deploys your website to GitHub Pages when you push to the main branch. **Triggers:** Push to main branch, manual dispatch @@ -187,10 +197,14 @@ Validates that all books and articles in bibliography files meet DOI requirement ``` . -β”œβ”€β”€ _quarto.yml # Main configuration file -β”œβ”€β”€ index.qmd # Book homepage/introduction -β”œβ”€β”€ chapter1.qmd # Sample chapter 1 -β”œβ”€β”€ chapter2.qmd # Sample chapter 2 +β”œβ”€β”€ _quarto.yml # Main configuration file (profile-based) +β”œβ”€β”€ _quarto-website.yml # Website-specific configuration +β”œβ”€β”€ _quarto-revealjs.yml # RevealJS slides configuration +β”œβ”€β”€ _quarto-handout.yml # PDF handout configuration +β”œβ”€β”€ index.qmd # Website homepage +β”œβ”€β”€ chapters/ # Chapter files +β”‚ β”œβ”€β”€ chapter1.qmd # Sample chapter 1 +β”‚ └── chapter2.qmd # Sample chapter 2 β”œβ”€β”€ references.qmd # References page β”œβ”€β”€ references.bib # BibTeX bibliography β”œβ”€β”€ styles.css # Custom CSS styles @@ -222,10 +236,10 @@ Validates that all books and articles in bibliography files meet DOI requirement This template includes two GitHub Actions workflows: ### Publishing Workflow (`publish.yml`) -Automatically builds and deploys your book to GitHub Pages when you push to the main branch. +Automatically builds and deploys your website to GitHub Pages when you push to the main branch. ### Link Checker Workflow (`check-links.yml`) -Automatically checks that all URLs in your book are reachable: +Automatically checks that all URLs in your website are reachable: - **Runs on**: Push to main, pull requests, weekly schedule (Mondays at 9:00 UTC), and manual trigger - **Checks**: All links in `.qmd`, `.md`, and `.html` files @@ -288,7 +302,7 @@ For more details, see the [Quarto documentation](https://quarto.org/docs/guide/) ### Changing themes -Edit the `format.html.theme` section in `_quarto.yml`: +Edit the `format.html.theme` section in `_quarto-website.yml`: ```yaml format: @@ -298,19 +312,23 @@ format: dark: darkly # Try: darkly, cyborg, slate, superhero, etc. ``` -### Adding chapters +### Adding pages -1. Create a new `.qmd` file (e.g., `chapter3.qmd`) -2. Add it to the `chapters` list in `_quarto.yml`: +1. Create a new `.qmd` file (e.g., `chapters/chapter3.qmd`) +2. Add it to the navigation menu in `_quarto-website.yml`: ```yaml -book: - chapters: - - index.qmd - - chapter1.qmd - - chapter2.qmd - - chapter3.qmd # Your new chapter - - references.qmd +website: + navbar: + left: + - text: "Chapters" + menu: + - text: "Chapter 1: Introduction" + href: chapters/chapter1.qmd + - text: "Chapter 2: Advanced Topics" + href: chapters/chapter2.qmd + - text: "Chapter 3: Your New Chapter" + href: chapters/chapter3.qmd ``` ### Custom CSS diff --git a/README.md b/README.md index 617f6ff..62e07e8 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,26 @@ -# qbt (Quarto Book Template) +# qwt (Quarto Website Template) -A template repository for creating books with +A template repository for creating websites with [Quarto](https://quarto.org/). This template provides everything you -need to quickly start writing your own book. +need to quickly start writing your own website. ## Features -- πŸ“š **Book-ready structure** with sample chapters and references +- 🌐 **Website-ready structure** with sample chapters and references - 🎨 **Customizable themes** supporting light and dark modes - πŸš€ **Automatic deployment** to GitHub Pages via GitHub Actions - πŸ”— **Automated link checking** to ensure all URLs are reachable -- πŸ“„ **Multiple output formats** including HTML, PDF, EPUB, and DOCX +- οΏ½οΏ½ **Multiple output formats** including HTML, PDF, RevealJS slides, and DOCX - πŸ“‘ **Bibliography support** with BibTeX integration - πŸ”’ **Automatic numbering** of sections and cross-references -- πŸ’… **Custom CSS** for styling your book +- πŸ’… **Custom CSS** for styling your website - πŸ” **PR Preview** with change highlighting for pull requests - βœ… **Automated checks** including spell checking and linting - πŸ€– **GitHub Copilot integration** with custom setup steps @@ -30,7 +30,7 @@ need to quickly start writing your own book. ### Using this template -1. Click the β€œUse this template” button at the top of this repository +1. Click the "Use this template" button at the top of this repository 2. Name your new repository and create it 3. Clone your new repository to your local machine @@ -51,74 +51,86 @@ To verify Quarto is installed: quarto --version ``` -### Customize your book +### Customize your website -1. **Edit `_quarto.yml`** to update: +1. **Edit `_quarto-website.yml`** to update: - - Book title and author + - Website title and site URL - Repository URL - - Chapter list + - Navigation menu items - Theme and styling options -2. **Modify `index.qmd`** to create your book’s homepage/introduction +2. **Modify `index.qmd`** to create your website's homepage -3. **Edit or create chapters** (`.qmd` files): +3. **Edit or create pages** (`.qmd` files): - - Modify `chapter1.qmd` and `chapter2.qmd` as needed - - Create new chapters and add them to the `chapters` list in - `_quarto.yml` + - Modify files in the `chapters/` directory as needed + - Create new pages and add them to the navigation menu in + `_quarto-website.yml` 4. **Add references** to `references.bib` in BibTeX format 5. **Customize styling** in `styles.css` -## Building the book +## Building the website ### Local preview -To preview your book with live reload during development: +To preview your website with live reload during development: ``` bash quarto preview ``` -This will open your book in a web browser and automatically refresh when -you make changes. +This will open your website in a web browser and automatically refresh +when you make changes. -### Render the book +### Render the website -To render the complete book: +To render the complete website: ``` bash quarto render ``` -The output will be generated in the `docs/` directory. +The output will be generated in the `_site/` directory. + +### Multiple output formats + +This template supports multiple output formats through Quarto profiles: + +- **Website** (default): `quarto render` or + `quarto render --profile website` +- **RevealJS slides**: `quarto render --profile revealjs` (output in + `_slides/`) +- **PDF handouts**: `quarto render --profile handout` (output in + `_handouts/`) ## Publishing to GitHub Pages This template includes a GitHub Actions workflow (`.github/workflows/publish.yml`) that automatically builds and -publishes your book to GitHub Pages when you push to the main branch. +publishes your website to GitHub Pages when you push to the main +branch. ### Setup steps: 1. **Enable GitHub Pages** in your repository: - Go to Settings β†’ Pages - - Under β€œBuild and deployment”, set Source to β€œGitHub Actions” + - Under "Build and deployment", set Source to "GitHub Actions" 2. **Push to main branch**: ``` bash git add . - git commit -m "Initial book setup" + git commit -m "Initial website setup" git push origin main ``` 3. **Wait for the workflow** to complete (check the Actions tab) -4. **Access your book** at: +4. **Access your website** at: `https://YOUR-USERNAME.github.io/YOUR-REPO/` ## GitHub Actions Workflows @@ -128,8 +140,8 @@ development experience: ### πŸš€ Publish Workflow (`publish.yml`) -Automatically builds and deploys your book to GitHub Pages when you push -to the main branch. +Automatically builds and deploys your website to GitHub Pages when you +push to the main branch. **Triggers:** Push to main branch, manual dispatch @@ -148,7 +160,7 @@ unlabeled **Labels:** - Add `no-preview-highlights` label to disable change highlighting if - it’s glitchy + it's glitchy ### βœ… Spell Check Workflow (`check-spelling.yaml`) @@ -167,7 +179,7 @@ Checks R code style and quality using the lintr package. ### πŸ€– Copilot Setup Steps (`copilot-setup-steps.yml`) -Configures the GitHub Copilot coding agent’s environment with Quarto and +Configures the GitHub Copilot coding agent's environment with Quarto and TinyTeX. **Triggers:** Workflow dispatch, changes to the setup file @@ -197,10 +209,14 @@ ensures all citations are properly traceable. ## Project Structure . - β”œβ”€β”€ _quarto.yml # Main configuration file - β”œβ”€β”€ index.qmd # Book homepage/introduction - β”œβ”€β”€ chapter1.qmd # Sample chapter 1 - β”œβ”€β”€ chapter2.qmd # Sample chapter 2 + β”œβ”€β”€ _quarto.yml # Main configuration file (profile-based) + β”œβ”€β”€ _quarto-website.yml # Website-specific configuration + β”œβ”€β”€ _quarto-revealjs.yml # RevealJS slides configuration + β”œβ”€β”€ _quarto-handout.yml # PDF handout configuration + β”œβ”€β”€ index.qmd # Website homepage + β”œβ”€β”€ chapters/ # Chapter files + β”‚ β”œβ”€β”€ chapter1.qmd # Sample chapter 1 + β”‚ └── chapter2.qmd # Sample chapter 2 β”œβ”€β”€ references.qmd # References page β”œβ”€β”€ references.bib # BibTeX bibliography β”œβ”€β”€ styles.css # Custom CSS styles @@ -232,12 +248,12 @@ This template includes two GitHub Actions workflows: ### Publishing Workflow (`publish.yml`) -Automatically builds and deploys your book to GitHub Pages when you push -to the main branch. +Automatically builds and deploys your website to GitHub Pages when you +push to the main branch. ### Link Checker Workflow (`check-links.yml`) -Automatically checks that all URLs in your book are reachable: +Automatically checks that all URLs in your website are reachable: - **Runs on**: Push to main, pull requests, weekly schedule (Mondays at 9:00 UTC), and manual trigger @@ -251,8 +267,8 @@ Automatically checks that all URLs in your book are reachable: To manually trigger the link checker: 1. Go to the Actions tab in your repository -2. Select β€œCheck Links” workflow -3. Click β€œRun workflow” +2. Select "Check Links" workflow +3. Click "Run workflow" ## Writing Content @@ -304,7 +320,7 @@ documentation](https://quarto.org/docs/guide/). ### Changing themes -Edit the `format.html.theme` section in `_quarto.yml`: +Edit the `format.html.theme` section in `_quarto-website.yml`: ``` yaml format: @@ -314,19 +330,23 @@ format: dark: darkly # Try: darkly, cyborg, slate, superhero, etc. ``` -### Adding chapters +### Adding pages -1. Create a new `.qmd` file (e.g., `chapter3.qmd`) -2. Add it to the `chapters` list in `_quarto.yml`: +1. Create a new `.qmd` file (e.g., `chapters/chapter3.qmd`) +2. Add it to the navigation menu in `_quarto-website.yml`: ``` yaml -book: - chapters: - - index.qmd - - chapter1.qmd - - chapter2.qmd - - chapter3.qmd # Your new chapter - - references.qmd +website: + navbar: + left: + - text: "Chapters" + menu: + - text: "Chapter 1: Introduction" + href: chapters/chapter1.qmd + - text: "Chapter 2: Advanced Topics" + href: chapters/chapter2.qmd + - text: "Chapter 3: Your New Chapter" + href: chapters/chapter3.qmd ``` ### Custom CSS diff --git a/_quarto-handout.yml b/_quarto-handout.yml new file mode 100644 index 0000000..174b9dc --- /dev/null +++ b/_quarto-handout.yml @@ -0,0 +1,34 @@ +project: + output-dir: _handouts + render: + - "index.qmd" + - "chapters/chapter1.qmd" + - "chapters/chapter2.qmd" + +format: + pdf: + geometry: + - top=15mm + - bottom=20mm + keep-md: false + keep-tex: false + toc: true + fig-pos: "H" + toc-title: Contents + df-print: tibble + links-as-notes: true + documentclass: article + colorlinks: true + number-sections: true + number-depth: 3 + +execute: + warning: false + message: false + cache: false + freeze: auto + +knitr: + opts_chunk: + collapse: true + comment: "#>" diff --git a/_quarto-revealjs.yml b/_quarto-revealjs.yml new file mode 100644 index 0000000..ef916e8 --- /dev/null +++ b/_quarto-revealjs.yml @@ -0,0 +1,44 @@ +project: + output-dir: _slides + +format: + revealjs: + lightbox: true + theme: simple + embed-resources: false + fig-cap-location: top + html-math-method: mathjax + smaller: true + number-sections: true + progress: true + incremental: false + df-print: paged + number-depth: 2 + slide-number: true + shift-heading-level-by: -1 + slide-level: 2 + scrollable: true + echo: true + margin: 0.0 + code-fold: true + code-link: true + code-summary: "[R code]" + auto-stretch: true + fig-height: 5 + fig-width: 7 + chalkboard: true + preview-links: auto + controls: true + transition: slide + background-transition: fade + +execute: + warning: false + message: false + cache: false + freeze: auto + +knitr: + opts_chunk: + collapse: true + comment: "#>" diff --git a/_quarto-website.yml b/_quarto-website.yml new file mode 100644 index 0000000..90454c9 --- /dev/null +++ b/_quarto-website.yml @@ -0,0 +1,102 @@ +project: + type: website + output-dir: _site + render: + - "*.qmd" + - "chapters/*.qmd" + - "!README.md" + - "!appendix-document-metadata.qmd" + - "!references.qmd" + +website: + title: "Quarto Website Template" + site-url: https://ucd-serg.github.io/qwt/ + description: "A template for creating websites with Quarto" + page-footer: + center: "Built with [Quarto](https://quarto.org/)" + back-to-top-navigation: true + page-navigation: true + reader-mode: true + repo-url: https://github.com/UCD-SERG/qwt + repo-actions: [edit, issue, source] + navbar: + left: + - text: "Home" + href: index.qmd + - text: "Chapters" + menu: + - text: "Chapter 1: Introduction" + href: chapters/chapter1.qmd + - text: "Chapter 2: Advanced Topics" + href: chapters/chapter2.qmd + +format: + html: + theme: + light: cosmo + dark: darkly + css: styles.css + toc: true + toc-location: right + toc-depth: 3 + code-fold: false + code-tools: true + code-link: true + highlight-style: pygments + lightbox: true + link-external-icon: true + embed-resources: false + fig-cap-location: top + html-math-method: mathjax + number-sections: true + number-depth: 3 + df-print: paged + date: last-modified + date-format: "[Last modified:] YYYY-MM-DD HH:mm:ss (z)" + docx: + toc: true + toc-depth: 3 + number-sections: true + number-depth: 3 + df-print: tibble + prefer-html: true + revealjs: + output-file: "{stem}-slides.html" + theme: simple + slide-number: true + chalkboard: false + preview-links: auto + controls: true + transition: slide + background-transition: fade + lightbox: true + fig-cap-location: top + html-math-method: mathjax + smaller: true + number-sections: true + progress: true + incremental: false + df-print: paged + number-depth: 2 + shift-heading-level-by: -1 + slide-level: 2 + scrollable: true + echo: true + margin: 0.0 + code-fold: true + code-link: true + code-summary: "[R code]" + auto-stretch: true + fig-height: 5 + fig-width: 7 + +execute: + warning: false + message: false + cache: false + freeze: auto + +knitr: + opts_chunk: + collapse: true + comment: "#>" diff --git a/_quarto.yml b/_quarto.yml index a321cae..6003f90 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -1,59 +1,22 @@ -project: - type: book - output-dir: docs - -book: - title: "Your Book Title" - author: "Your Name" - date: last-modified - date-format: "[Last updated:] YYYY-MM-DD" - repo-url: https://github.com/UCD-SERG/qbt - repo-actions: [edit, source, issue] - downloads: [pdf, epub, docx] - chapters: - - index.qmd - - chapter1.qmd - - chapter2.qmd - - references.qmd - page-navigation: true +profile: + default: website bibliography: references.bib -format: - html: - theme: - light: cosmo - dark: darkly - css: styles.css - toc: true - number-sections: true - embed-resources: false - pdf: - geometry: - - top=15mm - - bottom=20mm - keep-md: false - keep-tex: false - toc: true - fig-pos: "H" - hyperrefoptions: - - bookmarksnumbered=true - toc-title: Contents - df-print: tibble - links-as-notes: true - documentclass: scrbook - classoption: [twoside=off] - shift-heading-level-by: 0 - toc-depth: 2 - number-sections: true - number-depth: 3 - colorlinks: true - docx: - toc: false - number-sections: true - highlight-style: github - epub: - toc: true - number-sections: true +editor_options: + chunk_output_type: console + +editor: + markdown: + wrap: 72 + +execute: + warning: false + message: false + cache: false + freeze: auto -editor: source +knitr: + opts_chunk: + collapse: true + comment: "#>" diff --git a/appendix-document-metadata.qmd b/appendix-document-metadata.qmd new file mode 100644 index 0000000..3ff4321 --- /dev/null +++ b/appendix-document-metadata.qmd @@ -0,0 +1,42 @@ +# Document Generation Metadata {.unnumbered} + +::: {.content-visible when-format="docx"} +This document was generated from the following git commit: + +```{r} +#| echo: false +#| output: asis + +# Get git branch +branch <- system("git rev-parse --abbrev-ref HEAD 2>/dev/null", intern = TRUE) +if (length(branch) == 0 || branch == "") branch <- "unknown" + +# Get short commit hash +commit_short <- system("git rev-parse --short HEAD 2>/dev/null", intern = TRUE) +if (length(commit_short) == 0 || commit_short == "") commit_short <- "unknown" + +# Get full commit hash +commit_full <- system("git rev-parse HEAD 2>/dev/null", intern = TRUE) +if (length(commit_full) == 0 || commit_full == "") commit_full <- "unknown" + +# Get commit date +commit_date <- "git show -s --format=%ci HEAD 2>/dev/null" |> + system(intern = TRUE) +if (length(commit_date) == 0 || commit_date == "") commit_date <- "unknown" + +# Print formatted output +cat("- **Branch:**", branch, "\n") +cat("- **Commit:**", commit_short, "\n") +cat("- **Full commit hash:**", commit_full, "\n") +cat("- **Commit date:**", commit_date, "\n") +``` + +When transferring edits from this DOCX file back to the Quarto source files, +use this commit information to set up the PR correctly and account for any commits that have been added since this document was generated. +::: + + + + + + diff --git a/chapter1.qmd b/chapters/chapter1.qmd similarity index 62% rename from chapter1.qmd rename to chapters/chapter1.qmd index 3a5bfaa..bdb43fb 100644 --- a/chapter1.qmd +++ b/chapters/chapter1.qmd @@ -1,6 +1,18 @@ +--- +title: "Chapter 1: Introduction" +format: + html: default + revealjs: + output-file: chapter1-slides.html + pdf: + output-file: chapter1-handout.pdf + docx: + output-file: chapter1.docx +--- + # Chapter 1: Introduction -This is the first chapter of your book. Replace this content with your own. +This is the first chapter of your website. Replace this content with your own. ## Section 1.1 @@ -41,3 +53,10 @@ ggplot(mtcars, aes(x = wt, y = mpg)) + ## Section 1.3 Include citations using `@citationkey` format, which references entries in your `references.bib` file. + +## References {.unnumbered} + +::: {#refs} +::: + +{{< include ../appendix-document-metadata.qmd >}} diff --git a/chapter2.qmd b/chapters/chapter2.qmd similarity index 72% rename from chapter2.qmd rename to chapters/chapter2.qmd index d221234..751810a 100644 --- a/chapter2.qmd +++ b/chapters/chapter2.qmd @@ -1,6 +1,18 @@ +--- +title: "Chapter 2: Advanced Topics" +format: + html: default + revealjs: + output-file: chapter2-slides.html + pdf: + output-file: chapter2-handout.pdf + docx: + output-file: chapter2.docx +--- + # Chapter 2: Advanced Topics -This is the second chapter. Continue building your book with more chapters. +This is the second chapter. Continue building your website with more chapters. ## Mathematical Equations @@ -50,3 +62,10 @@ This is a warning callout. Alert readers to potential issues. ::: {.callout-important} This is an important callout. Emphasize critical information. ::: + +## References {.unnumbered} + +::: {#refs} +::: + +{{< include ../appendix-document-metadata.qmd >}} diff --git a/index.qmd b/index.qmd index e1582f2..dbe01b0 100644 --- a/index.qmd +++ b/index.qmd @@ -1,42 +1,61 @@ +--- +title: "Quarto Website Template" +format: + html: default + revealjs: + output-file: index-slides.html + pdf: + output-file: index-handout.pdf + docx: + output-file: index.docx +--- + # Welcome {.unnumbered} -This is a Quarto book template that you can use to create your own book. +This is a Quarto website template that you can use to create your own website. + +The notes are available in multiple formats: + +- **HTML Website**: Navigate using the navbar for easy access to all pages +- **RevealJS Slides**: Each chapter can generate a presentation format with `-slides.html` suffix +- **PDF Handouts**: Each chapter can generate a PDF handout with `-handout.pdf` suffix +- **DOCX Documents**: Each chapter can generate a Microsoft Word document with `.docx` extension -## About this book +## About this website -This book is built with [Quarto](https://quarto.org/), an open-source scientific and technical publishing system. You can use Quarto to create books, websites, blogs, presentations, and more from markdown files. +This website is built with [Quarto](https://quarto.org/), an open-source scientific and technical publishing system. You can use Quarto to create books, websites, blogs, presentations, and more from markdown files. ## Getting Started To use this template: -1. **Update the configuration**: Edit `_quarto.yml` to change the book title, author, repository URL, and chapters. +1. **Update the configuration**: Edit `_quarto-website.yml` to change the website title, site URL, and navigation menu. -2. **Add your content**: Create new `.qmd` files for each chapter and add them to the `chapters` list in `_quarto.yml`. +2. **Add your content**: Create new `.qmd` files for each page and add them to the navigation menu in `_quarto-website.yml`. -3. **Customize the style**: Modify `styles.css` to change the appearance of your book. +3. **Customize the style**: Modify `styles.css` to change the appearance of your website. 4. **Add references**: Update `references.bib` with your citations. -## Building the book +## Building the website -To render the book locally: +To render the website locally: ```bash quarto render ``` -To preview the book with live reload: +To preview the website with live reload: ```bash quarto preview ``` -The rendered output will be in the `docs/` directory, which can be published to GitHub Pages. +The rendered output will be in the `_site/` directory, which can be published to GitHub Pages. ## Publishing to GitHub Pages -This template includes a GitHub Actions workflow that automatically builds and publishes your book to GitHub Pages when you push to the main branch. +This template includes a GitHub Actions workflow that automatically builds and publishes your website to GitHub Pages when you push to the main branch. To enable GitHub Pages: @@ -44,10 +63,17 @@ To enable GitHub Pages: 2. Navigate to "Pages" in the left sidebar 3. Under "Build and deployment", set Source to "GitHub Actions" 4. Push your changes to the main branch -5. The workflow will automatically build and deploy your book +5. The workflow will automatically build and deploy your website -Your book will be available at `https://YOUR-USERNAME.github.io/YOUR-REPO/` +Your website will be available at `https://YOUR-USERNAME.github.io/YOUR-REPO/` ## License Add your license information here. + +## References {.unnumbered} + +::: {#refs} +::: + +{{< include appendix-document-metadata.qmd >}} diff --git a/inst/WORDLIST b/inst/WORDLIST index 9d5ea86..cb625f9 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -1,10 +1,12 @@ DOCX -EPUB +RevealJS SERG TinyTeX UCD +ebsite emplate glitchy lintr -ook +navbar +qmd uarto diff --git a/references.qmd b/references.qmd index 925f7c4..46868aa 100644 --- a/references.qmd +++ b/references.qmd @@ -1,4 +1,18 @@ +--- +title: "References" +format: + html: default + revealjs: + output-file: references-slides.html + pdf: + output-file: references-handout.pdf + docx: + output-file: references.docx +--- + # References {.unnumbered} ::: {#refs} ::: + +{{< include appendix-document-metadata.qmd >}}