From 35aaf0d3bfe78d93587c728d02d3fd140354e23f Mon Sep 17 00:00:00 2001 From: 0zgeKaplan <136622649+0zgeKaplan@users.noreply.github.com> Date: Thu, 16 May 2024 14:50:22 -0400 Subject: [PATCH] Initial commit --- .github/workflows/render-and-publish.yml | 35 +++++++ .gitignore | 9 ++ .nojekyll | 0 LICENSE | 121 +++++++++++++++++++++++ README.md | 53 ++++++++++ _quarto.yml | 63 ++++++++++++ content/acknowledgements.qmd | 5 + content/add-content.qmd | 25 +++++ content/code.qmd | 29 ++++++ content/customizing.qmd | 17 ++++ content/publishing.qmd | 94 ++++++++++++++++++ content/rendering.qmd | 21 ++++ content/rmarkdown.Rmd | 29 ++++++ favicon.ico | Bin 0 -> 15406 bytes include-files.lua | 115 +++++++++++++++++++++ index.qmd | 22 +++++ theme-dark.scss | 26 +++++ theme.scss | 6 ++ 18 files changed, 670 insertions(+) create mode 100644 .github/workflows/render-and-publish.yml create mode 100644 .gitignore create mode 100644 .nojekyll create mode 100644 LICENSE create mode 100644 README.md create mode 100644 _quarto.yml create mode 100644 content/acknowledgements.qmd create mode 100644 content/add-content.qmd create mode 100644 content/code.qmd create mode 100644 content/customizing.qmd create mode 100644 content/publishing.qmd create mode 100644 content/rendering.qmd create mode 100644 content/rmarkdown.Rmd create mode 100644 favicon.ico create mode 100644 include-files.lua create mode 100644 index.qmd create mode 100644 theme-dark.scss create mode 100644 theme.scss diff --git a/.github/workflows/render-and-publish.yml b/.github/workflows/render-and-publish.yml new file mode 100644 index 0000000..00bca25 --- /dev/null +++ b/.github/workflows/render-and-publish.yml @@ -0,0 +1,35 @@ +on: + push: + branches: main + +name: Render and Publish + +jobs: + build-deploy: + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v2 + + - name: Set up R (needed for Rmd) + uses: r-lib/actions/setup-r@v2 + + - name: Install packages (needed for Rmd) + run: Rscript -e 'install.packages(c("rmarkdown", "knitr", "jsonlite"))' + + - name: Set up Quarto + uses: quarto-dev/quarto-actions/setup@v2 + with: + # To install LaTeX to build PDF book + tinytex: true + # uncomment below and fill to pin a version + # version: 0.9.600 + + # add software dependencies here + + - name: Publish to GitHub Pages (and render) + uses: quarto-dev/quarto-actions/publish@v2 + with: + target: gh-pages + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # this secret is always available for github actions diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..823de20 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +.Rproj.user +.Rhistory +.RData +.Ruserdata +*.Rproj + +.DS_Store +/.quarto/ +/_site/ diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..0e259d4 --- /dev/null +++ b/LICENSE @@ -0,0 +1,121 @@ +Creative Commons Legal Code + +CC0 1.0 Universal + + CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE + LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN + ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS + INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES + REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS + PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM + THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED + HEREUNDER. + +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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..973ddc4 --- /dev/null +++ b/README.md @@ -0,0 +1,53 @@ +[![](https://img.shields.io/badge/Open%20In-RStudio%20Cloud-green)](https://rstudio.cloud/content/4771757) *Try without installing anything. Make sure to click the Make a Copy button or you will lose all your changes.* + +# NOAA quarto simple website with R in qmd or Rmd files + +This is a template for [a simple Quarto website](https://nmfs-opensci.github.io/NOAA-quarto-simple/) (`type: website`). It looks like a html book (`type: book`) but unlike the book type it only has html format and you will not have the download options. `type: website` is a common format for documentation. + +The repo includes a GitHub Action that will build the website automatically when you make changes to the files. The webpage will use the `gh-pages` branch. Serving the website files from this branch is a common way to keep all the website files from cluttering your main branch. + +**Warning:** Check that the settings will allow the GitHub Action to run. See the instructions below under "GitHub Set-up". Scroll down to the troubleshooting section if the website is not built by the GitHub Action. + +**Note:** The GitHub Action installs R so you can render qmd files with R code. You will need to edit to install Python or Julia if your qmd uses those instead. If you have substantial computations, you don't want to be re-running all the computations for files that didn't change. Read about the [freeze option](https://quarto.org/docs/publishing/ci.html) for this situation. R users with complex reports with dependencies (so qmd B depends on qmd A or data file A) should be aware of the {targets} package which will help you keep track of files that need to be re-rendered due to changes in dependencies. + +## GitHub Set-up + +* Click the green "Use This Template" button to make a repository with this content. Make sure to make your repo public (since GitHub Pages doesn't work on private repos unless you have a paid account) and check box to include all the branches (so that you get the gh-pages branch). +image + +* Turn on GitHub Pages under Settings > Pages . You will set pages to be made from the gh-pages branch and root directory. +image + +* Allow GitHub Actions under Settings > Actions > General +image + +* Allow GitHub Actions to write to the gh-pages branch. Scroll to the bottom under Settings > Actions > General, and make sure "Read and Write" is selected. +image + +* Edit the repo description and Readme to add a link to the webpage. When you edit the description, you will see the link url in the url box or you can click on the Actions tab or the Settings > Pages page to find the url to the Quarto website + +## Customize + +* Edit the qmd or md files in the `content` folder. qmd files can include code (R, Python, Julia) and lots of Quarto markdown bells and whistles (like call-outs, cross-references, auto-citations and much more). +* Add the files to `_quarto.yml` + +## Troubleshooting builds + +The most common trouble users run into is that the book is not rendering. Check the following: + +* The `gh-pages` branch does not exist. If you forgot to check the check box to include all the branches when you created the repo from the template then it won't exist. The Action will fail if the gh-pages branch does not already exist. You can create the branch and then push a change to main to trigger the Action to run again. +* The GitHub Pages has not been set. You need to go to Pages under settings, and set Pages to build from the `gh-pages` branch. +* You did not allow GitHub Actions to run and/or did not give read/write permission. Go to Settings > Actions > General, and make sure Actions are allowed (top section) and they have read/write permission (bottom section). +* You did not push a change to the main branch. The Action is triggered by a push to main, so try making an edit to README.md and pushing that change. + +
+ +### Disclaimer + +This repository is a scientific product and is not official communication of the National Oceanic and Atmospheric Administration, or the United States Department of Commerce. All NOAA GitHub project content is provided on an ‘as is’ basis and the user assumes responsibility for its use. Any claims against the Department of Commerce or Department of Commerce bureaus stemming from the use of this GitHub project will be governed by all applicable Federal law. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government. + +### License + +This content was created by U.S. Government employees as part of their official duties. This content is not subject to copyright in the United States (17 U.S.C. §105) and is in the public domain within the United States of America. Additionally, copyright is waived worldwide through the CC0 1.0 Universal public domain dedication. + +
diff --git a/_quarto.yml b/_quarto.yml new file mode 100644 index 0000000..d38783c --- /dev/null +++ b/_quarto.yml @@ -0,0 +1,63 @@ +project: + type: website + +website: + page-navigation: true + title: "NOAA quarto simple" + site-url: "https://nmfs-opensci.github.io/NOAA-quarto-simple" + repo-url: "https://github.com/nmfs-opensci/NOAA-quarto-simple" + repo-actions: [edit, source, issue] + favicon: images/favicon.ico + + page-footer: + right: "This page is built with [Quarto](https://quarto.org/)." + left: "© CC-1.0" + + sidebar: + background: "#D9E3E4" + logo: "https://raw.githubusercontent.com/nmfs-opensci/assets/main/logo/nmfs-opensci-logo3.png" + favicon: images/favicon.ico + pinned: true + align: center + tools: + - icon: globe + href: https://nmfs-opensci.github.io + text: "NMFS Open Science" + - icon: github + href: https://github.com/nmfs-opensci + text: "NMFS OpenSci" + + style: "docked" + search: true + collapse-level: 1 + contents: + - href: index.qmd + text: Home + - href: content/add-content.qmd + text: Add content + - href: content/customizing.qmd + text: Customizing + - href: content/rendering.qmd + text: Rendering + - href: content/rmarkdown.Rmd + text: R Markdown files + - href: content/code.qmd + text: Code in your files + - href: content/acknowledgements.qmd + text: Acknowledgements + +format: + html: + theme: + light: [cosmo, theme.scss] + dark: [cosmo, theme-dark.scss] + code-copy: true + code-overflow: wrap + toc: true + + +filters: + - include-files.lua + - quarto + + diff --git a/content/acknowledgements.qmd b/content/acknowledgements.qmd new file mode 100644 index 0000000..8c6c83c --- /dev/null +++ b/content/acknowledgements.qmd @@ -0,0 +1,5 @@ +--- +title: Acknowledgments +--- + +This repo and GitHub Action was based on the tutorial by Openscapes [quarto-website-tutorial](https://github.com/Openscapes/quarto-website-tutorial) by Julia Lowndes and Stefanie Butland. \ No newline at end of file diff --git a/content/add-content.qmd b/content/add-content.qmd new file mode 100644 index 0000000..f1885ef --- /dev/null +++ b/content/add-content.qmd @@ -0,0 +1,25 @@ +--- +title: Customize +--- + +## Edit and add your pages + +Edit the qmd or md files in the `content` folder. qmd files can include code (R, Python, Julia) and lots of Quarto markdown bells and whistles (like call-outs, cross-references, auto-citations and much more). + +Each page should start with +``` +--- +title: your title +--- +``` +and the first header will be the 2nd level, so `## `. Note, there are situations where you leave off +``` +--- +title: your title +--- +``` +and start the qmd file with a level header `# `, but if using the default title yaml (in the `---` fence) is a good habit since it makes it easy for Quarto convert your qmd file to other formats (like into a presentation). + +## Add your pages the project + +* Add the files to `_quarto.yml` diff --git a/content/code.qmd b/content/code.qmd new file mode 100644 index 0000000..762f9ff --- /dev/null +++ b/content/code.qmd @@ -0,0 +1,29 @@ +--- +title: Rendering with Code +--- + +You can have code (R, Python or Julia) in your qmd file. You will need to have these installed on your local computer, but presumably you do already if you are adding code to your qmd files. + +```{r echo=TRUE} +x <- c(5, 15, 25, 35, 45, 55) +y <- c(5, 20, 14, 32, 22, 38) +lm(x ~ y) +``` + + +## Modify the GitHub Action + +You will need to change the GitHub Action in `.github/workflows` to install these and any needed packages in order for GitHub to be able to render your webpage. The GitHub Action install R since I used that in `code.qmd`. If you use Python or Julia instead, then you will need to update the GitHub Action to install those. + +If getting the GitHub Action to work is too much hassle (and that definitely happens), you can alway render locally and publish to the `gh-pages` branch. If you do this, make sure to delete or rename the GitHub Action to something like +``` +render-and-publish.old_yml +``` +so GitHub does not keep trying to run it. Nothing bad will happen if you don't do this, but if you are not using the action (because it keeps failing), then you don't need GitHub to run it. + +## Render locally and publish to gh-pages branch + +To render locally and push up to the `gh-pages` branch, open a terminal window and then `cd` to the directory with the Quarto project. Type this in the terminal: +``` +quarto render gh-pages +``` diff --git a/content/customizing.qmd b/content/customizing.qmd new file mode 100644 index 0000000..766c2ae --- /dev/null +++ b/content/customizing.qmd @@ -0,0 +1,17 @@ +--- +title: Customization +--- + +## Quarto documentation + +Quarto allow many bells and whistles to make nice output. Read the documentation here [Quarto documentation](https://quarto.org/docs/guide/). + +## Examples + +Looking at other people's Quarto code is a great way to figure out how to do stuff. Most will have a link to a GitHub repo where you can see the raw code. Look for a link to edit page or see source code. This will usually be on the right. Or look for the GitHub icon somewhere. + +* [Quarto gallery](https://quarto.org/docs/gallery/) +* [nmfs-openscapes](https://nmfs-openscapes.github.io/) +* [Faye lab manual](https://thefaylab.github.io/lab-manual/) +* [quarto-titlepages](https://nmfs-opensci.github.io/quarto_titlepages/) Note the link to edit is broken. Go to repo and look in `documentation` directory. + diff --git a/content/publishing.qmd b/content/publishing.qmd new file mode 100644 index 0000000..4106dbd --- /dev/null +++ b/content/publishing.qmd @@ -0,0 +1,94 @@ +--- +title: Publishing +--- + +To get your Quarto webpage to show up with the url +``` +yourname.github.io/yourrepo +``` +you have a few steps. + +## Turn on GitHub Pages for your repo + +* Turn on GitHub Pages under Settings > Pages . You will set pages to be made from the gh-pages branch and the root directory. +* Turn on GitHub Actions under Settings > Actions > General + +The GitHub Action will automatically recreate your website when you push to GitHub **after** you do the initial `gh-pages` set-up + +## Do your first publish to `gh-pages` + +The first time you publish to `gh-pages`, you need to do so locally. + +* On your local computer, open a terminal window and `cd` to your repo directory. Here is what that `cd` command looks like for me. You command will look different because your local repo will be somewhere else on your computer. +``` +cd ~/Documents/GitHub/NOAA-quarto-simple +``` +* Publish to the `gh-pages`. In the terminal type +``` +quarto publish gh-pages +``` +This is going to render your webpage and then push the `_site` contents to the `gh-pages` branch. + + +## Don't like using `gh-pages`? + +In some cases, you don't want your website on the `gh-pages` branch. For example, if you are creating releases and you want the website pages archived in that release, then you won't want your website pages on the `gh-pages` branch. + +Here are the changes you need to make if you to avoid `gh-pages` branch. + +* At the top of `_quarto.yml` add the following: +``` +project: + type: website + output-dir: docs +``` +* On GitHub under Settings > Pages set pages to be made from the `main` branch and the docs directory. +* Make sure `docs` is not listed in `.gitignore` +* Publish the site the first time locally using `quarto publish` from the terminal +* Change the GitHub Action because you can't use `quarto publish gh-pages`. You'll need to push to the main branch yourself (in the GitHub Action) +``` +on: + push: + branches: main + +name: Render and Publish + +jobs: + build-deploy: + runs-on: ubuntu-latest + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + + steps: + - name: Check out repository + uses: actions/checkout@v2 + + - name: Set up R (needed for Rmd) + uses: r-lib/actions/setup-r@v2 + + - name: Install packages (needed for Rmd) + run: Rscript -e 'install.packages(c("rmarkdown", "knitr", "jsonlite"))' + + - name: Set up Quarto + uses: quarto-dev/quarto-actions/setup@v2 + with: + # To install LaTeX to build PDF book + # tinytex: true + # uncomment below and fill to pin a version + # version: 0.9.600 + + - name: Render Quarto Project + uses: quarto-dev/quarto-actions/render@v2 + with: + to: html + + - name: Set up Git + run: | + git config --local user.email "actions@github.com" + git config --local user.name "GitHub Actions" + + - name: Commit all changes and push + run: | + git add -A && git commit -m 'Build site' || echo "No changes to commit" + git push origin || echo "No changes to commit" +``` diff --git a/content/rendering.qmd b/content/rendering.qmd new file mode 100644 index 0000000..b68366b --- /dev/null +++ b/content/rendering.qmd @@ -0,0 +1,21 @@ +--- +title: Rendering +--- + +The repo includes a GitHub Action that will render (build) the website automatically when you make changes to the files. It will be pushed to the `gh-pages` branch. + +But when you are developing your content, you will want to render it locally. + +## Step 1. Make sure you have a recent RStudio + +Have you updated RStudio since about August 2022? No? Then update to a newer version of RStudio. In general, you want to keep RStudio updated and it is required to have a recent version to use Quarto. + +## Step 2. Clone and create RStudio project + +First, clone the repo onto your local computer. How? You can click File > New Project and then select "Version Control". Paste in the url of the repository. That will clone the repo on to your local computer. When you make changes, you will need to push those up. + +## Step 3. Render within RStudio + +RStudio will recognize that this is a Quarto project by the presence of the `_quarto.yml` file and will see the "Build" tab. Click the "Render website" button to render to the `_site` folder. + +**Previewing:** You can either click `index.html` in the `_site` folder and specify "preview in browser" or set up RStudio to preview to the viewer panel. To do the latter, go to Tools > Global Options > R Markdown. Then select "Show output preview in: Viewer panel". diff --git a/content/rmarkdown.Rmd b/content/rmarkdown.Rmd new file mode 100644 index 0000000..6d551ef --- /dev/null +++ b/content/rmarkdown.Rmd @@ -0,0 +1,29 @@ +--- +title: "R Markdown" +--- + +```{r setup, include=FALSE} +knitr::opts_chunk$set(echo = TRUE) +``` + +You can include R Markdown files in your project. + +## R Markdown + +This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see . + +When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this: + +```{r cars} +summary(cars) +``` + +## Including Plots + +You can also embed plots, for example: + +```{r pressure, echo=FALSE} +plot(pressure) +``` + +Note that the `echo = FALSE` parameter was added to the code chunk to prevent printing of the R code that generated the plot. diff --git a/favicon.ico b/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..e9beabcef39fb2f5777344299209542e0a1d90da GIT binary patch literal 15406 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 literal 0 HcmV?d00001 diff --git a/include-files.lua b/include-files.lua new file mode 100644 index 0000000..b933836 --- /dev/null +++ b/include-files.lua @@ -0,0 +1,115 @@ +--- include-files.lua – filter to include Markdown files +--- +--- Copyright: © 2019–2021 Albert Krewinkel +--- License: MIT – see LICENSE file for details + +-- Module pandoc.path is required and was added in version 2.12 +PANDOC_VERSION:must_be_at_least '2.12' + +local List = require 'pandoc.List' +local path = require 'pandoc.path' +local system = require 'pandoc.system' + +--- Get include auto mode +local include_auto = false +function get_vars (meta) + if meta['include-auto'] then + include_auto = true + end +end + +--- Keep last heading level found +local last_heading_level = 0 +function update_last_level(header) + last_heading_level = header.level +end + +--- Update contents of included file +local function update_contents(blocks, shift_by, include_path) + local update_contents_filter = { + -- Shift headings in block list by given number + Header = function (header) + if shift_by then + header.level = header.level + shift_by + end + return header + end, + -- If image paths are relative then prepend include file path + Image = function (image) + if path.is_relative(image.src) then + image.src = path.normalize(path.join({include_path, image.src})) + end + return image + end, + -- Update path for include-code-files.lua filter style CodeBlocks + CodeBlock = function (cb) + if cb.attributes.include and path.is_relative(cb.attributes.include) then + cb.attributes.include = + path.normalize(path.join({include_path, cb.attributes.include})) + end + return cb + end + } + + return pandoc.walk_block(pandoc.Div(blocks), update_contents_filter).content +end + +--- Filter function for code blocks +local transclude +function transclude (cb) + -- ignore code blocks which are not of class "include". + if not cb.classes:includes 'include' then + return + end + + -- Markdown is used if this is nil. + local format = cb.attributes['format'] + + -- Attributes shift headings + local shift_heading_level_by = 0 + local shift_input = cb.attributes['shift-heading-level-by'] + if shift_input then + shift_heading_level_by = tonumber(shift_input) + else + if include_auto then + -- Auto shift headings + shift_heading_level_by = last_heading_level + end + end + + --- keep track of level before recusion + local buffer_last_heading_level = last_heading_level + + local blocks = List:new() + for line in cb.text:gmatch('[^\n]+') do + if line:sub(1,2) ~= '//' then + local fh = io.open(line) + if not fh then + io.stderr:write("Cannot open file " .. line .. " | Skipping includes\n") + else + local contents = pandoc.read(fh:read '*a', format).blocks + last_heading_level = 0 + -- recursive transclusion + contents = system.with_working_directory( + path.directory(line), + function () + return pandoc.walk_block( + pandoc.Div(contents), + { Header = update_last_level, CodeBlock = transclude } + ) + end).content + --- reset to level before recursion + last_heading_level = buffer_last_heading_level + blocks:extend(update_contents(contents, shift_heading_level_by, + path.directory(line))) + fh:close() + end + end + end + return blocks +end + +return { + { Meta = get_vars }, + { Header = update_last_level, CodeBlock = transclude } +} diff --git a/index.qmd b/index.qmd new file mode 100644 index 0000000..c2fd926 --- /dev/null +++ b/index.qmd @@ -0,0 +1,22 @@ +--- +title: "NOAA quarto simple with R" +subtitle: "A simple Quarto webpage with a book layout" +page-layout: full +--- + +This is a template for a simple Quarto website that looks like a "book". This is a common format for documentation. It includes a GitHub Action that will build the website automatically when you make changes to the files. The NOAA palette and fonts has been added to `theme.scss`. The webpage will be on the `gh-pages` branch. Serving the website files from this branch is a common way to keep all the website files from cluttering your main branch. + +The GitHub Action installs R so you can have R code in your qmd or Rmd files. Note, you do not need to make changes to your Rmd files unless your need Quarto features like cross-references. + +## GitHub Set-up + +* Click the green "use template" button to make a repository with this content. Make sure to make your repo public (since GitHub Pages doesn't work on private repos unless you have a paid account) and check box to include all the branches (so that you get the gh-pages branch). +image + +* Turn on GitHub Pages under Settings > Pages . You will set pages to be made from the gh-pages branch and root directory. +image + +* Turn on GitHub Actions under Settings > Actions > General +image + +* Edit the repo description and Readme to add a link to the webpage. When you edit the description, you will see the link url in the url box or you can click on the Actions tab or the Settings > Pages page to find the url. diff --git a/theme-dark.scss b/theme-dark.scss new file mode 100644 index 0000000..9e645de --- /dev/null +++ b/theme-dark.scss @@ -0,0 +1,26 @@ +/*-- scss:defaults --*/ + +@import 'https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible&display=swap'; + +$font-family: "Atkinson Hyperlegible", sans-serif; + +// Base document colors +$body-bg: #181818; +$body-color: white; +$link-color: #75AADB; + +$light: #525252; + +// Navigation element colors +$footer-bg: #181818; +$navbar-bg: #303030; +$sidebar-bg: #303030; + +// Code blocks +$code-block-bg-alpha: -.8; + +// Bootstrap popovers +$popover-bg: #242424; + +// Bootstrap inputs +$input-bg: #242424; diff --git a/theme.scss b/theme.scss new file mode 100644 index 0000000..ce0550a --- /dev/null +++ b/theme.scss @@ -0,0 +1,6 @@ +/*-- scss:defaults --*/ + +@import 'https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible&display=swap'; + +$font-family: "Atkinson Hyperlegible", sans-serif; +