87 lines
4.6 KiB
Markdown
87 lines
4.6 KiB
Markdown
---
|
|
title: Website Publication Files
|
|
cuid: 26e4-a0
|
|
trls: [ nl ]
|
|
lang: en
|
|
---
|
|
|
|
How I create web pages from selected files from this repository, with private and public editions.
|
|
|
|
<!--summary-above-->
|
|
|
|
## Quickstart
|
|
|
|
Prerequisites: install [node](https://nodejs.org) and [git](https://git-scm.com); clone [the source](https://git.surfacemarkup.net/hans/ad_pubfiles) with `git clone https://git.surfacemarkup.net/hans/ad_pubfiles`.
|
|
|
|
0. In this repository, `npm install` dependencies, including [Web Origami](https://weborigami.org). The following instructions assume you also have installed the `ori` command with `npm install -g @weborigami/origami`. If not, replace `ori` in commands below with `npx @weborigami/origami`.
|
|
|
|
1. link or copy `README.md` to the parent directory of this repository, with the name `ad_pubfiles_pub.ori.md`. Now you have input for testing and development, since the ori template files look in the parent directory for files with this pattern. Optionally add more files with the pattern: `[a-p]+_title[_pub-other-tags][.ori].md`. That is:
|
|
|
|
- they MUST start with a sequence of characters `a-p`,
|
|
- followed by an underscore,
|
|
- followed by a title which does not contain an underscore,
|
|
- followed optionally by an underscore and one or more tags separated by hyphens. For testing purposes, only the `pub` tag is relevant.
|
|
- followed by the filetype extension `.md`. If you want to use Origami expressions in the file, use `.ori.md`.
|
|
|
|
The reason for this setup step is that on my machine, the parent directory contains my personal wiki. So I can't share the input with you directly. The filename pattern above is used for the process of selecting which files to include in the build. The [figure below](#project-structure-figure) shows this arrangement.
|
|
|
|
2. Use the following commands to achieve the desired output.
|
|
|
|
- in private mode: `ori "serve watch ., =debug ./site.ori('all')"`
|
|
- in public mode: `ori "serve watch ., =debug ./site.ori()"`
|
|
|
|
`site.ori` only exposes the final rendering step from `pipeline.ori`. Therefore:
|
|
|
|
- To serve the pipeline with all the processing steps available for inspection, replace `site.ori` with `pipeline.ori` in the commands above.
|
|
|
|
|
|
<figure class="wider" id="project-structure-figure">
|
|
<img src="/ad_pubfiles_pub.d/project-structure.svg" alt="a diagram showing a directory called src containing markdown files. The src directory also contains a subdirectory called ad_pubfiles_pub.d. Arrows show that the file README.md inside this subdirectory is hardlinked to a file in the parent src directory, and that the file pipeline.ori in the subdirectory reads markdown files from the parent src directory, and that the subdirectory is a git repository which is synchronized with a remote public repository.">
|
|
<figcaption>How the site generator files relate to the content</figcaption>
|
|
</figure>
|
|
|
|
|
|
|
|
|
|
|
|
<trl-group>
|
|
<trl-alt lang="en">
|
|
|
|
## Markup Language
|
|
I have developed a text markup format which suits my needs better than Markdown. The parser works and I can render HTML with it, but the feature set is still very limited. For example, I can only render single works in italic. That might seem like an odd sort of limitation, but it's because I've started from somewhat different first principles than the assumptions the HTML/Markdown worfklow is based on. As we all know, the last 10% takes the most work. So for now, I'm formatting the source files in Markdown.
|
|
|
|
</trl-alt>
|
|
<trl-alt lang="nl">
|
|
|
|
## Markup-taal
|
|
Ik heb een formaat ontwikkeld voor tekst die beter bij mijn doelen past dan Markdown. Het werkt, en ik kan er HTML mee genereren, maar er is nog een heleboel dat het nog niet kan. Omdat de laatste 10% altijd het meeste werk is, gebruik ik voor nu Markdown.
|
|
|
|
</trl-alt>
|
|
|
|
</trl-group>
|
|
|
|
## Changes and Updates
|
|
This section SHALL describe the idea behind the [Changelog](/changelog).
|
|
|
|
## Source files
|
|
The scripts and templates used to build this site are available [here](https://git.surfacemarkup.net/hans/ad_pubfiles).
|
|
|
|
<p>—private-below—</p>
|
|
|
|
EXCEPT NOT REALLY! In this case, because this file is hardlinked to `README.md` inside a publicised git repository. You have been warned!
|
|
|
|
## Internal Links
|
|
|
|
|
|
Internal links need to be absolute from the root of the directory. This SHOULD be fixed in a future version.
|
|
|
|
|
|
## Web Origami, Public and Private Site Versions
|
|
I want to make only select files public. Files whose name contains the tag `pub` should be included in the public build. The public build should be the default. To include all files, pass 'all' to the site.ori file. That sort of reduces the risk of accidentally publishing private files.
|
|
|
|
|
|
|
|
## Organisation
|
|
|
|
${ada_pubfiles-worklog.md/}
|