graph TD; A[rectangle] --> B((circle with<br>line break)) --> C[/slanted/]
Page priority: Low
Updating: Frequent while preparation methods are being tested.
Comments to sp17@cornell.edu .
This is about composing and self-publishing interlinked technical documents consisting of hypertext pages. It applies to NYSDEC project outreach material, the NYSDEC 2021-2025 monitoring project’s Quality Assurance Plan and HowTos, and possibly other Cornell Soil and Water Lab hypertext material. It is grouped with the NYSDEC 2021-2025 QAPP as an earliest application.
Change log:
| When | Who | Comments |
|---|---|---|
| 2023 06 21 | Sp17 | First version, temporarily grouped with the NYSDEC 2021-2025 QAPP. |
| 2023 06 22 | Sp17 | Refined the “how to review” section. |
| 2023 07 04 | Sp17 | Elaborated on page composition in Markdown language with extensions. This reflects the refactoring of all DEC web material to have the QAPP as a subset of the main DEC pages. |
| 2023 07 31 | Sp17 | Revised to describe Quarto instead of MkDocs as the static site renderer. Added bibliography example. |
1. Objectives
- Create reviewable hypertext material for procedural documents that can be shared via WWW.
- Limit the amount of web composing literacy required.
- Focus creativity on structure of material rather than appearance on paper.
- Standardize some aspects.
- Facilitate separate editing paths for each document (page).
Future:
- Reviewability.
- Better incorporation of bibliographic content.
- Non-Cornell composers of independent material.
2. Approach
2.1 Hypertext for the order of visiting
Hypertext material consists of a group of short documents (“pages” of varying lengths) that are linked together via referring to one another and by an index of closely related peer documents. An earlier mode document such as a journal article, book, or technical report is fundamentally linear, and comes from a printed book legacy of equal-sized consecutive pages. By 2023 we have a great alternative to linearly sequenced, equal sized pages. This evolved via Vannevar Bush’s Memex in the 1940’s, Ted Nelson’s Xanadu in the 1960’s, and Tim Berners-Lee’s WorldWideWeb in the 1990s. Today we visit web pages in any order and sometimes we open several at a time and easily flick back and forth.
Academic personnel produce millions of journal articles per year which contain external references. Today’s online journal papers include references lists that link to online versions of the references, thus creating a hypertext (hypermedia) web of journal articles. This HowTo provides a methodology for self-publishing a similar web of content with a Page as the quantum, smaller than a linear journal paper.
This HowTo exists to encourage migration to hypertext navigation of unequal sized pages at a level below the journal article.
2.2 Component pages
Markdown for body rich text and headings
The Markdown language provides an easy-to-learn way to create technical content for publishing as individual pages and in hypertext webs of pages, and even in other formats such as PDF.
Markdown adds to plain text certain simple punctuation for headings, lists, and phrase emphasis like italic and boldface. There are simple textual ways to make links between separate pages using their file names – refer to the other Markdown source file name (ending in .qmd or .md). There are slightly more elaborate ways to make tables, and there are extensions for text expressions representing equations and bibliographic citations.
Mermaid for diagrams
The Mermaid language, like Markdown using structured typable text, adds diagramming which is helpful for many technical projects. For example:
```{mermaid} %%| label: fig-mermaid %%| fig-cap: "Caption for Mermaid diagram" graph TD; A[rectangle] --> B((circle with<br>line break)) --> C[/slanted/] ```
renders to:
The two %%| items are for figure numbering and titling. The figure may be referred to by @fig-mermaid rendering as “Figure 1”. This use of a symbol allows ignoring figure and table numbers.
There is a Mermaid book.
Mathematical notation
There are means to represent equations in Markdown using another textual sublanguage. Here are the equation sublanguages in text form:
- How about an integral?
$$
f(x) = \int_{-\infty}^\infty
\hat f(\xi)\,e^{2 \pi i \xi x}
\,d\xi
$$
- How about an inline between dollar signs: $\sqrt{3x-1}+(1+x)^2$Which result in:
- How about an integral?
f(x) = \int_{-\infty}^\infty
\hat f(\xi)\,e^{2 \pi i \xi x}
\,d\xi
- How about an inline between dollar signs: \sqrt{3x-1}+(1+x)^2
This uses the MathJax Javascript implementation of the LaTeX syntax.
Footnotes and bibliographic citations
Markdown provides a footnoting approach that uses the structure [^1] inline and the structure [^1]: Footnote body to fill in the body of a footnote. The latter may appear anywhere in the page but is rendered at the bottom of the page. The footnote marker ^1 can be any word, not only a numeral, which eliminates the need to renumber notes. The rendering into HTML places all of the footnote bodies at the end of the page and there are in-page navigation jumps between the bibliography item and the narrative that link to one another.1
The Pandoc extension to Markdown, which Quarto uses to convert extended Markdown into HTML and other formats, provides a means to insert formal literature citations into Markdown documents that are rendred somewhat like footnotes. The @richardsPerennialGrassBioenergy2014b bibliographic citation renders to Richards et al. (2014) inline or to (Richards et al. (2014)) if in parentheses, and appends a bibliographic list of this one item at the end of this page. The bibliopgraphic list will be before the footnote body list.
Embedded graphics
Editors allow easy insertion of graphics in files or pasting from the clipboard, into Markdown text. This is somewhat like referring to another page, though typically the graphic will be shown inline. The Markdown structure for this is . PNG graphics such as screen captures can also be inserted.
In VSCode (see section 3 below), an extension uses Ctrl-Alt-V to insert a graphic while editing; the reference to the graphic must be converted into the {#fig-figshortname} syntax manually.
3. Tools for authoring individual pages and sets of pages
Tools aid in composing a set of page files in Markdown, such as Microsoft’s free Visual Studio Code editor (Figure 2).
In this screencap, the dark left column is an index of many Markdown (file name with .qmd) pages, with some included PNG graphics files. The dark center column is the Markdown file being edited as structured text, and the light right column is how the Markdown file looks when rendered in a way close to how it would look on web if converted to HTML. VSCode keeps the rendered column in sync with the current text in the center column, as long as you save the file you are working on (including via autosave). (The preview can be turned off.)
For VSCode, the following extensions are necessary or important: - Markdown All in One - Quarto - Paste Image
VSCode makes internal cross-links between pages open the destination page for viewing or editing, when clicked or ctrl-clicked.
RStudio can also provide a means to compose as set of web pages using the Quarto framework.
Any other text editor can be used to create or modify Markdown files. VSCode and RStudio have the advantage of providing rendered previewing.
4. Creating the web of pages
To “publish” beyond the person composing the pages requires a static site generator program. This converts all of the set of md files into HTML for local viewing or transmitting to a web server, including changing the internal cross-links from ones to Markdown files into ones to HTML files. The converted version is a frozen snapshot, and to edit anything requires going back to the Markdown .md files.
The publishing also creates any extra navigation indices.
Prior to 2023, all of SWL’s web content was of a “static” nature, mostly composed without the help of static site generator software.
4.1 Quarto static site generator
We use the Quarto software as the generator starting from grouped Markdown pages, among several free software choices. Hugo and MkDocs were also considered.
In Figure 3 the left column is a hierarchical index of all HowTo documents of the set, in an order specified in a _quarto.yml configuration file. The right column is an index of the section headers in the current page, allowing quick jumps to different parts of the current page.
The output from Quarto will look different in a phone or tablet web browser, or in a narrow window on a laptop.
4.2 Installing Quarto
Download from quarto.org an installer package and install.
If using VSCode, install the Quarto extension.
In recent RStudio, there is a Quarto instance provided, or the downloaded version of standalone Quarto can be used.
4.3 Operating Quarto beyond page composition
The .qmd files of a set need to be in a directory or subdirectories, by convention named qdocs. In the top level directory there is a configuration file called _quarto.yml, and usually an index.qmd file that becomes the default entry point index.html when the HTML is uploaded to a web server. The configuration file enumerates all .qmd files in a desired navigational order; Quarto’s rendered navigation section provides for a foldable hierarchy of pages by having a “section” construct that contains only a heading without a link.
An abbreviated version of the _quarto.yml file for the DEC+QAPP pageset, as of 2023-07-31, is:
project:
type: website
title: "DEC Pesticides 2021-2025"
crossref:
fig-prefix: Figure
tbl-prefix: Table
ref-hyperlink: true
number-sections: false
citeproc: true
citations-hover: true
citation-location: document
bibliography: c:/users/space/OneDrive/Documents/MyLibrary.bib
csl: c:/users/space/OneDrive/Documents/elsevier-vancouver-author-date.csl
website:
title: "NYSDEC Pesticides 2021-2025"
page-footer: "Greetings from Tammo Steenhuis and Brian Richards, Principal Investigators!"
page-navigation: true
sidebar:
style: "docked"
search: true
contents:
- section: "The Project"
contents:
- href: index.qmd
text: Project home page
(omissions for brevity)
- section: "Methods"
contents:
- href: methods.qmd
text: Methods intro
- href: methods-detail-site-characterization.qmd
text: Site characterization
(omissions for brevity)
- section: "Background material"
contents:
- href: qapp/HowTo-contract-scope.qmd
text: Contract scope
- href: qapp/Meta-HowTo-HowTos.qmd
text: Intention and mechanics of HowTos
navbar:
logo: logo2.PNG
background: primary
left:
- href: https://soilandwaterlab.cornell.edu/
text: SWL home
- href: qapp/index.qmd
text: Project QAPP
format:
html:
theme: cosmo
css: styles.css
html-math-method: katex
toc: true
toc-location: right
Quarto can render all files into html and serve them locally for previewing before they are uploaded to a web server. Using a Windows terminal (on one of sp17’s computers where the .qmd files are stored in OneDrive – Box Drive did not work for previewing):
cd c:\users\space\OneDrive\work\DEC\web\qdocs
quarto previewThis will render all .qmd files into HTML and serve them locally, via a localhost URL it displays. Open this in a browser like Chrome or Edge. The browser that loads this URL will auto-refresh every time a .qmd or .yml file changes, thus the author can keep tailoring the content and the indexing order. Use control-c in the terminal window to terminate the server.
Once satisfied with the appearance and navigation, to build the HTML files for uploading:
cd c:\users\space\OneDrive\work\DEC\web\qdocs
quarto renderThen we upload the _site folder, that Quarto placed within the the qdocs folder, to SWL’s Pantheon web server. We place this uploaded folder in the Pantheon WordPress directory /wp-content/uploads/static/ so that it is visible at URL
https://dev-cornell-soil-and-water-lab-homepage.pantheonsite.io/wp-content/uploads/static/dec-web/
Access the SWL Pantheon site for uploading using
https://dev-cornell-soil-and-water-lab-homepage.pantheonsite.io/wp-admin/
in a browser which requires login as user soilandwaterlab. (Password is available from sp17.) Use the WP File Manager (a WordPress plugin) for navigation to the wp-content/uploads/static directory, then delete the destination directory _site if it already exists, and finally upload. The _site name can be friendlier if set in the _quarto.yml file, or it can be renamed in the WordPress file manager.
The ‘dev’ site at Pantheon is not intended for public discovery; however, there is currently no security from anyone who knows the above URL. To get content published for the public, it needs to be cloned using Pantheon’s dashboard to the ‘live’ instance and to be linked to some already-visible material. After complete cloning the content will be visible at:
https://soilandwaterlab.cornell.edu/wp-content/uploads/static/_site/
probably with _site replaced.
4.4 Summary from pages to published
graph TD; A[Compose or update in VSCode]; A-->C[Preview<br>with Quarto]; I[/_quarto.yml specs<br>for pageset<br>navigation and theme/]-->F; GG[/Graphics/]-->C Screenshots-->GG Photos-->GG M[/Markdown<br>pages/]; M-->A A-->M A-->I I-->C C-->A M-->F[Render with Quarto] M-->C GG-->F F-->D[Upload to 'dev' Soil and Water Lab<br>web server at Pantheon] D-->G[Verify with 'dev' at Pantheon] G-->E[Migrate from 'dev' to 'live'<br>instance at Pantheon]
5. Tools for reviewing
(needs work)
The entire _site directory can be zipped and sent. After unzipping, the reviewer loads the _site/index.html file into a browser and navigation will work as it does online. (The entire content is “static” and uses relative internal links, thus not requiring a web server to browse locally.)
Last updated 2023-07-31 sp17 AT cornell.edu
References
Richards B, Stoof C, Hansen J, Crawford R, Crawford J. Perennial grass bioenergy on marginal soils of the Northeast. Progressive Forage Grower 2014;15:8–9.
Footnotes
Body of footnote one.↩︎