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 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--> <!--summary-above-->
## Quickstart
## The Engine Prerequisites: [node](https://nodejs.org); [git](https://git-scm.com); clone this repository with `git clone https://git.surfacemarkup.net/hans/ad_pubfiles`.
The static site is generated with [Web Origami](https://weborigami.org).
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-group>
<trl-alt lang="en"> <trl-alt lang="en">
@ -32,10 +55,9 @@ I have developed a text markup format which suits my needs better than Markdown.
## Markup-taal ## Markup-taal
Ik heb een formaat ontwikkeld voor tekst die beter bij mijn doelen past dan Markdown. Ik heb een formaat ontwikkeld voor tekst die beter bij mijn doelen past dan Markdown.
</trl-alt> </trl-alt>
</trl-group> </trl-group>
## Internal Links ## 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