hans
/
ad_pubfiles
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

README: quickstart section

This commit is contained in:
Hans Fast 2026-03-25 10:13:37 +01:00
parent e1455783c8
commit da749db12a
2 changed files with 352 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
README.md
View File

@ -5,21 +5,44 @@ trls: [ nl ]
lang: en
---
This describes how I publish selected files from this repository to the Web. Actually, these files _are_ the publication mechanism.
How I create web pages from selected files from this repository, with private and public editions.
<!--summary-above-->
## Quickstart
## The Engine
The static site is generated with [Web Origami](https://weborigami.org).
Prerequisites: [node](https://nodejs.org); [git](https://git-scm.com); clone this repository 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>
`pipeline.ori` contains the main pipeline. `site.ori` selects some keys from `pipeline.ori` to create the final site. The reason for this split is: there are a bunch of steps in the pipeline which should not be exposed in the final build, but that do need to be accessible for inspection during development/debugging.
Both files take an argument which specifies whether to build the site in public or private mode. In public mode, only files with a certain tag are included in the output.
Public mode is the default. Run: `ori site.ori()` or `ori pipeline.ori()`.
For private mode, run: `ori 'site.ori("all")'` or `ori 'pipeline.ori("all")'`.
<trl-group>
<trl-alt lang="en">
@ -32,10 +55,9 @@ I have developed a text markup format which suits my needs better than Markdown.
## Markup-taal
Ik heb een formaat ontwikkeld voor tekst die beter bij mijn doelen past dan Markdown.
</trl-alt>
</trl-group>
## Internal Links

321
project-structure.svg Normal file
View File

@ -0,0 +1,321 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
width="240.31155mm"
height="158.17592mm"
viewBox="0 0 240.31155 158.17592"
version="1.1"
id="svg1"
inkscape:version="1.3.2 (091e20e, 2023-11-25)"
sodipodi:docname="project-structure.svg"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg">
<sodipodi:namedview
id="namedview1"
pagecolor="#ffffff"
bordercolor="#000000"
borderopacity="0.25"
inkscape:showpageshadow="2"
inkscape:pageopacity="0.0"
inkscape:pagecheckerboard="0"
inkscape:deskcolor="#d1d1d1"
inkscape:document-units="mm"
inkscape:zoom="0.76791526"
inkscape:cx="457.08168"
inkscape:cy="204.44964"
inkscape:window-width="1883"
inkscape:window-height="1056"
inkscape:window-x="37"
inkscape:window-y="0"
inkscape:window-maximized="1"
inkscape:current-layer="layer1" />
<defs
id="defs1">
<marker
style="overflow:visible"
id="Dot"
refX="0"
refY="0"
orient="auto"
inkscape:stockid="Dot"
markerWidth="1"
markerHeight="1"
viewBox="0 0 1 1"
inkscape:isstock="true"
inkscape:collect="always"
preserveAspectRatio="xMidYMid">
<path
transform="scale(0.5)"
style="fill:context-stroke;fill-rule:evenodd;stroke:none"
d="M 5,0 C 5,2.76 2.76,5 0,5 -2.76,5 -5,2.76 -5,0 c 0,-2.76 2.3,-5 5,-5 2.76,0 5,2.24 5,5 z"
sodipodi:nodetypes="sssss"
id="path17" />
</marker>
<marker
style="overflow:visible"
id="marker11"
refX="0"
refY="0"
orient="auto-start-reverse"
inkscape:stockid="Stylized triangle arrow"
markerWidth="1"
markerHeight="1"
viewBox="0 0 1 1"
inkscape:isstock="true"
inkscape:collect="always"
preserveAspectRatio="xMidYMid">
<path
transform="scale(0.5)"
style="fill:context-stroke;fill-rule:evenodd;stroke:context-stroke;stroke-width:1pt"
d="m 6,0 c -3,1 -7,3 -9,5 0,0 0,-4 2,-5 -2,-1 -2,-5 -2,-5 2,2 6,4 9,5 z"
id="path11" />
</marker>
<marker
style="overflow:visible"
id="ArrowTriangleStylized"
refX="0"
refY="0"
orient="auto-start-reverse"
inkscape:stockid="Stylized triangle arrow"
markerWidth="1"
markerHeight="1"
viewBox="0 0 1 1"
inkscape:isstock="true"
inkscape:collect="always"
preserveAspectRatio="xMidYMid">
<path
transform="scale(0.5)"
style="fill:context-stroke;fill-rule:evenodd;stroke:context-stroke;stroke-width:1pt"
d="m 6,0 c -3,1 -7,3 -9,5 0,0 0,-4 2,-5 -2,-1 -2,-5 -2,-5 2,2 6,4 9,5 z"
id="path4" />
</marker>
</defs>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(22.308297,-22.801204)">
<rect
style="fill:none;stroke:#000000;stroke-width:0.661458;stroke-linecap:round;stroke-linejoin:round"
id="rect1"
width="152.39316"
height="133.56699"
x="33.754688"
y="37.769974" />
<rect
style="fill:none;stroke:#000000;stroke-width:0.661458;stroke-linecap:round;stroke-linejoin:round"
id="rect2"
width="140.86958"
height="70.922546"
x="39.516479"
y="77.367867" />
<text
xml:space="preserve"
style="font-size:5.64444px;line-height:normal;font-family:'Drafting* Mono';-inkscape-font-specification:'Drafting* Mono';text-decoration-color:#000000;letter-spacing:-0.174625px;fill:#000000;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="35.446587"
y="36.580788"
id="text2"><tspan
sodipodi:role="line"
id="tspan2"
style="stroke-width:0.854"
x="35.446587"
y="36.580788">src</tspan></text>
<text
xml:space="preserve"
style="font-size:5.64444px;line-height:normal;font-family:'Drafting* Mono';-inkscape-font-specification:'Drafting* Mono';text-decoration-color:#000000;letter-spacing:-0.174625px;fill:#000000;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="40.572369"
y="76.105804"
id="text3"><tspan
sodipodi:role="line"
id="tspan3"
style="stroke-width:0.854"
x="40.572369"
y="76.105804">ad_pubfiles.d/</tspan></text>
<text
xml:space="preserve"
style="font-size:5.64444px;line-height:normal;font-family:'Drafting* Mono';-inkscape-font-specification:'Drafting* Mono';text-decoration-color:#000000;letter-spacing:-0.174625px;fill:#000000;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="40.565407"
y="45.987274"
id="text4"><tspan
sodipodi:role="line"
id="tspan4"
style="stroke-width:0.854"
x="40.565407"
y="45.987274">aa_README_pub.ori.md</tspan></text>
<text
xml:space="preserve"
style="font-size:5.64444px;line-height:normal;font-family:'Drafting* Mono';-inkscape-font-specification:'Drafting* Mono';text-decoration-color:#000000;letter-spacing:-0.174625px;fill:#000000;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="40.565407"
y="53.268227"
id="text5"><tspan
sodipodi:role="line"
id="tspan5"
style="stroke-width:0.854"
x="40.565407"
y="53.268227">ab_CHANGELOG_pub.ori.md</tspan></text>
<text
xml:space="preserve"
style="font-size:5.64444px;line-height:normal;font-family:'Drafting* Mono';-inkscape-font-specification:'Drafting* Mono';text-decoration-color:#000000;letter-spacing:-0.174625px;fill:#000000;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="40.565407"
y="60.549179"
id="text6"><tspan
sodipodi:role="line"
id="tspan6"
style="stroke-width:0.854"
x="40.565407"
y="60.549179">ad_pubfiles_pub.ori.md</tspan></text>
<text
xml:space="preserve"
style="font-size:5.64444px;line-height:normal;font-family:'Drafting* Mono';-inkscape-font-specification:'Drafting* Mono';text-decoration-color:#000000;letter-spacing:-0.174625px;fill:#000000;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="40.125549"
y="162.62843"
id="text7"><tspan
sodipodi:role="line"
id="tspan7"
style="stroke-width:0.854"
x="40.125549"
y="162.62843">pg_journal.md</tspan></text>
<text
xml:space="preserve"
style="font-size:5.64444px;line-height:normal;font-family:'Drafting* Mono';-inkscape-font-specification:'Drafting* Mono';text-decoration-color:#000000;letter-spacing:-0.174625px;fill:#000000;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="40.125549"
y="154.97641"
id="text8"><tspan
sodipodi:role="line"
id="tspan8"
style="stroke-width:0.854"
x="40.125549"
y="154.97641">...</tspan></text>
<path
style="fill:none;stroke:#000000;stroke-width:0.661458;stroke-linecap:round;stroke-linejoin:round"
d="M 33.754687,37.769974 V 32.441382 H 184.76596 l 1.38189,5.328592"
id="path8"
sodipodi:nodetypes="cccc" />
<path
style="fill:none;stroke:#000000;stroke-width:0.661458;stroke-linecap:round;stroke-linejoin:round"
d="m 39.516477,77.367867 -0.01161,-5.990051 139.499303,0.661459 1.38189,5.328592"
id="path9"
sodipodi:nodetypes="cccc" />
<text
xml:space="preserve"
style="font-size:5.64444px;line-height:normal;font-family:'Drafting* Mono';-inkscape-font-specification:'Drafting* Mono';text-decoration-color:#000000;letter-spacing:-0.174625px;fill:#000000;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="42.15987"
y="85.101646"
id="text9"><tspan
sodipodi:role="line"
id="tspan9"
style="stroke-width:0.854"
x="42.15987"
y="85.101646">README.md</tspan></text>
<path
style="fill:none;stroke:#6c6c6c;stroke-width:0.661458;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;marker-start:url(#marker11);marker-end:url(#ArrowTriangleStylized)"
d="M 36.641125,58.982847 C 21.755947,59.311244 20.687265,83.458182 35.78525,83.281314"
id="path10"
sodipodi:nodetypes="cc" />
<text
xml:space="preserve"
style="font-size:5.64444px;line-height:normal;font-family:'Drafting* Mono';-inkscape-font-specification:'Drafting* Mono';text-decoration-color:#000000;letter-spacing:-0.174625px;fill:#000000;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="42.15987"
y="100.49876"
id="text11"><tspan
sodipodi:role="line"
id="tspan11"
style="stroke-width:0.854"
x="42.15987"
y="100.49876">site.ori</tspan></text>
<text
xml:space="preserve"
style="font-size:5.64444px;line-height:normal;font-family:'Drafting* Mono';-inkscape-font-specification:'Drafting* Mono';text-decoration-color:#000000;letter-spacing:-0.174625px;fill:#000000;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="42.15987"
y="92.390984"
id="text12"><tspan
sodipodi:role="line"
id="tspan12"
style="stroke-width:0.854"
x="42.15987"
y="92.390984">pipeline.ori</tspan></text>
<text
xml:space="preserve"
style="font-size:5.64444px;line-height:normal;font-family:'Drafting* Mono';-inkscape-font-specification:'Drafting* Mono';text-decoration-color:#000000;letter-spacing:-0.174625px;fill:#000000;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="42.15987"
y="106.96966"
id="text13"><tspan
sodipodi:role="line"
id="tspan13"
style="stroke-width:0.854"
x="42.15987"
y="106.96966">...</tspan></text>
<text
xml:space="preserve"
style="font-size:5.64444px;line-height:normal;font-family:'Drafting* Mono';-inkscape-font-specification:'Drafting* Mono';text-decoration-color:#000000;letter-spacing:-0.174625px;fill:#000000;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="42.15987"
y="115.11634"
id="text15"><tspan
sodipodi:role="line"
id="tspan15"
style="stroke-width:0.854"
x="42.15987"
y="115.11634">.git</tspan></text>
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:5.64444px;line-height:normal;font-family:'Jost*';-inkscape-font-specification:'Jost*';text-align:end;text-decoration-color:#000000;letter-spacing:-0.174625px;text-anchor:end;fill:#6c6c6c;fill-opacity:1;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="23.416746"
y="69.783974"
id="text16"><tspan
sodipodi:role="line"
id="tspan16"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:'Jost*';-inkscape-font-specification:'Jost*';text-align:end;text-anchor:end;fill:#6c6c6c;fill-opacity:1;stroke-width:0.854"
x="23.416746"
y="69.783974">hardlinked.</tspan><tspan
sodipodi:role="line"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:'Jost*';-inkscape-font-specification:'Jost*';text-align:end;text-anchor:end;fill:#6c6c6c;fill-opacity:1;stroke-width:0.854"
x="23.242123"
y="76.839523"
id="tspan17">same file!</tspan></text>
<path
style="fill:none;stroke:#6c6c6c;stroke-width:0.661458;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;marker-end:url(#Dot)"
d="m 84.055528,90.909318 h 43.033912 c 29.62783,0 26.8537,-13.841089 27.08487,-26.159095"
id="path20"
sodipodi:nodetypes="csc" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:5.64444px;line-height:normal;font-family:'Jost*';-inkscape-font-specification:'Jost*';text-align:start;text-decoration-color:#000000;letter-spacing:-0.174625px;text-anchor:start;fill:#6c6c6c;fill-opacity:1;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="85.254784"
y="99.005234"
id="text20"><tspan
sodipodi:role="line"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:'Jost*';-inkscape-font-specification:'Jost*';text-align:start;text-anchor:start;fill:#6c6c6c;fill-opacity:1;stroke-width:0.854"
x="85.254784"
y="99.005234"
id="tspan21">reads md files from parent dir.</tspan><tspan
sodipodi:role="line"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:'Jost*';-inkscape-font-specification:'Jost*';text-align:start;text-anchor:start;fill:#6c6c6c;fill-opacity:1;stroke-width:0.854"
x="85.254784"
y="106.06078"
id="tspan23">Does not descend into dirs like this one.</tspan></text>
<path
style="fill:none;stroke:#6c6c6c;stroke-width:0.661458;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1;marker-end:url(#Dot)"
d="M 40.803687,114.47587 H 30.050997"
id="path23"
sodipodi:nodetypes="cc" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:5.64444px;line-height:normal;font-family:'Jost*';-inkscape-font-specification:'Jost*';text-align:start;text-decoration-color:#000000;letter-spacing:-0.174625px;text-anchor:start;fill:#6c6c6c;fill-opacity:1;stroke-width:0.854001;stroke-linecap:square;stroke-linejoin:round;-inkscape-stroke:none;stop-color:#000000"
x="-13.524602"
y="115.62434"
id="text26"><tspan
sodipodi:role="line"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:'Jost*';-inkscape-font-specification:'Jost*';text-align:start;text-anchor:start;fill:#6c6c6c;fill-opacity:1;stroke-width:0.854"
x="-13.524602"
y="115.62434"
id="tspan26">synced with public</tspan><tspan
sodipodi:role="line"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-family:'Jost*';-inkscape-font-specification:'Jost*';text-align:start;text-anchor:start;fill:#6c6c6c;fill-opacity:1;stroke-width:0.854"
x="-13.524602"
y="122.67989"
id="tspan27">remote repo</tspan></text>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB