diff --git a/_quarto.yml b/_quarto.yml index 5583106..4a86e5b 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -41,8 +41,8 @@ website: contents: - href: lessons/part1-quarto.qmd text: Edit a Quarto site - - href: lessons/demo.qmd - text: demo.qmd practice file +# - href: lessons/demo.qmd + # text: demo.qmd practice file - href: lessons/part2-github.qmd text: Contribute via GitHub - href: next-steps.qmd @@ -60,7 +60,6 @@ format: filters: - - include-files.lua - quarto diff --git a/include-files.lua b/include-files.lua deleted file mode 100644 index b933836..0000000 --- a/include-files.lua +++ /dev/null @@ -1,115 +0,0 @@ ---- 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 index bb78c7f..55fa2de 100644 --- a/index.qmd +++ b/index.qmd @@ -11,17 +11,19 @@ The ability for Quarto to streamline collaboration has been so cool and importan **To begin**, you should have a GitHub account with access to the 2i2c Openscapes JupyterHub. -## Purpose, Outcomes, Process ([POP](https://suzannehawkes.com/2010/04/09/pop-everything/)) +## Our Plan today -**Purpose:** NASA Openscapes Mentors learn workflows with Quarto and GitHub for contributing to the [NASA Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/) or any site or book made with Quarto. An opportunity for Mentors to connect and skill-build together. +We will learn workflows with Quarto and GitHub for contributing to open source documentation - like the [NASA Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/). -**Outcomes:** Mentors build skills and are more equipped and empowered to contribute. This is a new clinic we can reuse and build on. +This is a 1.5-hr clinic that has demos and time for hands-on practice in breakout rooms. -**Process:** A 1.5-hr clinic that can be used to teach or as self-paced learning. with demo's and hands-on practice to guide folks through contributing to existing Quarto sites & books. Analogous to our GitHub Clinic. The clinic content is contained in this website that is built with Quarto on GitHub; there are no accompanying slide decks. +**Part 1. Quarto Workflow:** Use the 2i2c Openscapes JupyterHub to explore this clinic website and its source repository on GitHub, practice contributing to this site by editing a Quarto file or adding a new Jupyter Notebook and previewing the changes. -1. Quarto Workflow: Use the 2i2c Openscapes JupyterHub to explore this clinic website and its source repository on GitHub, practice contributing to this site by editing a Quarto file or adding a new Jupyter Notebook and previewing the changes. +**Part 2. GitHub Workflow:** Clone the repository for this site, make a branch to work in, edit, commit and push your edits to GitHub, make a pull request, review and merge a pull request, and communicate what you’re doing at each step. -2. GitHub Workflow: Clone the repository for this site, make a branch to work in, edit, commit and push your edits to GitHub, make a pull request, review and merge a pull request, and communicate what you’re doing at each step. +This requires some setup. We'll do this first, and discuss more as we go. + + -See many more examples at the [Quarto gallery](https://quarto.org/docs/gallery/)! diff --git a/lessons/index.qmd b/lessons/index.qmd index d16de73..2324e80 100644 --- a/lessons/index.qmd +++ b/lessons/index.qmd @@ -4,17 +4,6 @@ title: Practice *TODO: Drastically reduce this page's text. Get to the doing. This index page should say, hey here's 2 things we'll practice - Edit a Quarto site, and Contribute via GitHub. Here's the Basic Workflow* -## Basic Workflow - -How do you work in Quarto? You can use whichever tool you're comfortable with (Jupyter, RStudio, GitHub, VS Code, etc). Developing your Quarto site will have the same basic workflow, no matter which tool you use. It is very iterative. - -1. Authoring: write text, code, images, etc in a file. Supported files include `.md`, `.Rmd`, `.qmd`, `.ipynb`... -2. Update `_quarto.yml` as needed (for example, if you've created a new file you'd like included in your site) -3. Render individual files and/or the whole website -4. Repeat, repeat, repeat -5. Commit and push your updates to GitHub, they will publish automatically! -6. Repeat all of the above to make the website as you'd like! - ## Authoring *TODO: Move to "Edit a Quarto site"* diff --git a/next-steps.qmd b/next-steps.qmd index bbcd3af..4d2a213 100644 --- a/next-steps.qmd +++ b/next-steps.qmd @@ -29,3 +29,16 @@ We can use these skills to contribute to many Quarto websites and books. - e.g. add a link to your slides or recording of a presentation - [Openscapes Approach Guide](https://openscapes.github.io/approach-guide/) - [Openscapes Champions Lessons Series](https://openscapes.github.io/series) + + +## Example Quarto sites + +- [NASA Openscapes](https://nasa-openscapes.github.io/) +- [NASA Earthdata Cloud Cookbook](https://nasa-openscapes.github.io/earthdata-cloud-cookbook/) +- [2021 NASA Cloud Hackathon](https://nasa-openscapes.github.io/2021-Cloud-Hackathon/) +- [Openscapes Champions Lessons Series](https://openscapes.github.io/series) +- [Openscapes Approach Guide](https://openscapes.github.io/approach-guide/) +- [Faylab Lab Manual](https://thefaylab.github.io/lab-manual/) +- [A Quarto tip a day](https://mine-cetinkaya-rundel.github.io/quarto-tip-a-day/), by Mine Çetinkaya-Rundel + +See many more examples at the [Quarto gallery](https://quarto.org/docs/gallery/)! diff --git a/setup-explore.qmd b/setup-explore.qmd index 98df25c..4de2de1 100644 --- a/setup-explore.qmd +++ b/setup-explore.qmd @@ -38,7 +38,9 @@ Most of these are pages, but you'll see that "Lessons" has an arrow `>`; it is a ### The website's source repo -*TODO: If we will make a new repo for every Clinic, we'll need to update the repo link below, every time.* + Let's go to this website's GitHub repository (or "repo"), . You can also click there from any page in this clinic website by clicking the GitHub Octocat icon underneath the Openscapes logo in the left navbar. @@ -54,6 +56,21 @@ To open a link in a new browser tab, hold command on Mac, or control on a PC, th ![quarto-website-tutorial GitHub repository with files for webpages marked with red arrows](images/quarto-files-github.png){fig-alt="Screenshot of files on GitHub with red arrows identifying the files that we saw in the left sidebar" fig-align="center" width="80%"} +### Quarto Basic Workflow + +Quarto is an open-source scientific and technical publishing system You can weave together narrative text and code to produce elegantly formatted output as documents, web pages, blog posts, books, presentations, and more. + +How do you work in Quarto? You can use whichever tool you're comfortable with (Jupyter, RStudio, GitHub, VS Code, etc). Developing your Quarto site will have the same basic workflow, no matter which tool you use. It is very iterative. + +1. Authoring: write text, code, images, etc in a file. Supported files include `.md`, `.Rmd`, `.qmd`, `.ipynb`... +2. Update `_quarto.yml` as needed (for example, if you've created a new file you'd like included in your site) +3. Render individual files and/or the whole website +4. Repeat, repeat, repeat +5. Commit and push your updates to GitHub, they will publish automatically! +6. Repeat all of the above to make the website as you'd like! + + + + ## Setup Part 2: Clone the Quarto Clinic repo After our Hub server has loaded (Setup Part 1), we'll clone the Quarto Clinic repository into the Hub.