Introduction to QPages
QPages is the NodeJS application that builds and publishes using primarily content maintained in markdown files (Obsidian Note). It reads the notes that are ready, fills each one into a page template, and writes ordinary HTML.
Writing
The pages of this site are Markdown files. We edit them in Obsidian Note. Fetch reads those files and imports them. Any markdown editor can be used. We prefer Obsidian Note because of the convenience to cross-link notes.
A note opens with a short header (frontmatter): the title, the address on the site, the template to use, and a status. The text before the first heading is the introduction, placed under the page headline. The rest of the note is the body. When the header names no template, the page template is used.
A note joins the site when its status is approved. Until then it stays in the folder, and Fetch leaves it there.
A link to another note wraps the note name in double brackets. A pipe and a label after the name choose the words on the page. When that note was fetched, the link uses the address from its header. When the note is absent from the fetch, the label stays on the page as plain text.
An aside is a blockquote whose first line names the style: a note, a warning, a success, an error, or a quieter line. A heading keeps the level written in the note.
Fetching
Fetch reads the sources named for a site and keeps what is ready to build. On this site those sources are Markdown notes and finished HTML pages. A source can also be a Git repository, CSV files, API calls or Database connectors.
A Markdown note is kept only when it is approved. The body stays Markdown, and the time the file was last changed is kept with it. A finished HTML page is kept whole. Render later copies it to the same place in the output, which is how a file such as a missing-page notice remains its own page.
Fetch can also read a collection on its own, such as photos or videos. Each note in that collection is kept as a record: the title, the description, and the other fields the note already contains. A field the note omits is absent from the record, and the record is still kept.
The result of a fetch is a working copy. It can be discarded. The next fetch rebuilds it from these cached files.
Rendering
Render reads the working copy for one site and writes the HTML.
A note is merged with its template. The template supplies the page header, the footer, and the scripts. Render supplies the title, the description, the headline, the introduction, and the body as HTML. An aside becomes a paragraph in the style named on its first line. From the second heading level down, each heading is given its own address, so a table of contents can point to it. Each section of the note becomes its own section on the page. Where the template includes a trail, the page shows one. Each step uses that page's short label, and the first step is the home page. The home template includes no trail.
The site address / becomes the home page file. Any other address becomes a folder with an index file inside it.
A page is written only when the new HTML differs from the file already on disk. The same applies to a finished HTML page copied through from the HTML source. A page that is no longer in the build is removed, and a folder left empty goes with it. Styles, scripts, and images stay where they are. A site with an empty working copy is left as it stands.
Deploying
Deploy posts the rendered html files to the host publishing the website. We use Firebase hosting. The rendered website is published with the command “firebase deploy —hosting. As the resulting website consists of static files only, othe hosting platforms can be used by their available methods to copy the files.