Docs structures may vary across different scripts, making it risky to link across topics.

Idea:

• Each article has a UUID
• Custom syntax for link-by-UUID
• UUID registry + link generation at build time
• Build failure or more graceful handling in case of missing link target

Wir bleiben in Kontakt.
Lg Alex R.

See feature/tabs-component for a first approach.

The MDX syntax should look about as follows:

# Instructions
Here are the instructions for each operating system.

::Tabs
:Tab :mdi-microsoft-windows: Windows
This is some text about Windows.

:Tab :mdi-apple: macOS
This is some text about macOS.

:Tab :mdi-linux: Linux
<details>
  <summary>See Linux instructions...</summary>
  <div>The instructions for Linux.</div>
</details>

::EndTabs

In styles.scss

/* Custom Infima classes for Admonitions */
.alert {
  &.alert--definition {
    // TODO: Fix for dark theme.
    --ifm-alert-background-color: #faefe7;
    --ifm-alert-background-color-highlight: #eaded7;
    --ifm-alert-foreground-color: #003100FF;
    --ifm-alert-border-color: #988c8a;
  }
}

• auto-generated source references (lincense info, caption, etc. in JSON) -> see ofi-blog
• Markdown support for caption (especially useful for italic/regular in sources)
• support for hero container / image border / drop shadow

https://github.com/remarkjs/remark-directive

Add support for SSR- or live-rendering draw.io diagrams from a draw.io a XML object in the codebase.

Under the hood, a *.drawio file looks like this:

<mxfile host="Electron" modified="2024-01-12T18:06:35.819Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/22.1.18 Chrome/120.0.6099.199 Electron/28.1.2 Safari/537.36" etag="GFLFRjP3Gb1FHmmebjOb" version="22.1.18" type="device">
  <diagram name="Page-1" id="zg5J133Pvn5T79VbdHT6">
    <mxGraphModel dx="984" dy="718" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <mxCell id="OexC0P_dEvz_FHYpmvae-2" value="Edit in draw.io desktop app" style="shape=step;perimeter=stepPerimeter;whiteSpace=wrap;html=1;fixedSize=1;fillColor=#f5f5f5;fontColor=#333333;strokeColor=#666666;" vertex="1" parent="1">
          <mxGeometry x="80" y="310" width="200" height="40" as="geometry" />
        </mxCell>
        <mxCell id="OexC0P_dEvz_FHYpmvae-3" value="Save XML in repo" style="shape=step;perimeter=stepPerimeter;whiteSpace=wrap;html=1;fixedSize=1;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;" vertex="1" parent="1">
          <mxGeometry x="260" y="310" width="150" height="40" as="geometry" />
        </mxCell>
        <mxCell id="OexC0P_dEvz_FHYpmvae-4" value="Render live or during build" style="shape=step;perimeter=stepPerimeter;whiteSpace=wrap;html=1;fixedSize=1;fillColor=#f8cecc;strokeColor=#b85450;" vertex="1" parent="1">
          <mxGeometry x="390" y="310" width="190" height="40" as="geometry" />
        </mxCell>
        <mxCell id="OexC0P_dEvz_FHYpmvae-5" value="Profit" style="shape=step;perimeter=stepPerimeter;whiteSpace=wrap;html=1;fixedSize=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
          <mxGeometry x="560" y="310" width="90" height="40" as="geometry" />
        </mxCell>
        <mxCell id="OexC0P_dEvz_FHYpmvae-6" value="Happy person" style="shape=umlActor;verticalLabelPosition=bottom;verticalAlign=top;html=1;outlineConnect=0;" vertex="1" parent="1">
          <mxGeometry x="670" y="290" width="30" height="60" as="geometry" />
        </mxCell>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Let's say we have a content page Some-Topic/Some-Article.mdx. We could then store a draw.io diagram under Some-Topic/assets/myDiagram.drawio. The MDX page might looks something like this:

# Some Article
Here's a diagram to visualize this concept:
::drawio[assets/myDiagram.drawio]

The ::drawio leaf directive implementation would then make a call to the draw.io renderer (most likely at build time) and replace the directive with the resulting image.

Works fine:

:::info Wozu wurde der dieser Computer entwickelt?
Der Micro:bit wurde von der BBC (_British Broadcasting Corporation_) entwickelt, damit Menschen von jung bis alt die
Grundlagen der Informatik auf spannende, kreative Weise entdecken können.
:::

Title is broken down into the body as a first line:

:::info Wozu wurde der Micro:bit entwickelt?
Der Micro:bit wurde von der BBC (_British Broadcasting Corporation_) entwickelt, damit Menschen von jung bis alt die
Grundlagen der Informatik auf spannende, kreative Weise entdecken können.
:::

The most obvious root cause is that the : in Micro:bit changes the AST enough for the current assumptions not to hold true anymore.

Important links

• GraphViz D3 syntax: https://www.graphviz.org/doc/info/lang.html
• d3-graphviz repo: https://github.com/magjac/d3-graphviz

The idea

For an MDX page such as

# Some graph
Here's a graph:
```dot render
digraph {a -> b}
``

the body of the dot render code block is rendered through and replaced by the result of https://github.com/magjac/d3-graphviz:

May be useful: https://github.com/actions/cache, https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows

Concept:

name: Deploy Application
run-name: ${{ github.actor }} is deploying the teaching website 🚀
on:
  push:
    branches:
      - main
      - feature/first-content
  pull_request:
    branches:
      - main
jobs:
  install_and_test:
    runs-on: ubuntu-latest
    name: Install dependencies and run tests
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Node setup
        uses: actions/setup-node@v2
        with:
          node-version: '20.x'
      - name: Yarn install
        run: yarn install --frozen-lockfile
      - name: Test
        run: yarn run test
      # TODO: Cache node installation, checked-out repo, node_modules
  build_and_deploy_sites:
    runs-on: ubuntu-latest
    needs: install_and_test
    name: Build and deploy all sites
    strategy:
      matrix:
        site: [ teach, gbsl, lerbermatt ]
    steps:
      # TODO: Load cached node installation, checked-out repo, node_modules
      - name: Build for site ${{ matrix.site }}
        run: SITE=${{ matrix.site }} npm run build
      - name: RSync to webhost
        uses: Burnett01/[email protected]
        with:
          switches: -avzr --delete
          path: build/
          remote_path: ~/sites/${{ matrix.site }}.silasberger.ch/
          remote_host: ${{ secrets.WEBHOST_SSH_HOSTNAME }}
          remote_user: ${{ secrets.WEBHOST_SSH_USERNAME }}
          remote_key: ${{ secrets.WEBHOST_SSH_PRIVATE_KEY }}

Candidates:

• everything in sync that doesn't yet have a .spec
• scripts-builder.ts
• site-config-loader.ts

• Main use cases for filters
  • Provide a specific alt to a file with equivalent canonical name
  • Restrict a file in a mapped folder to only a select set of scripts
• For all other use cases, prefer explicit mapping over filters (i.e. don't abuse filters)
• While markers were partly additive, markers are purely subtractive
• mapping application changes slightly from "do not include marked nodes" to "include filtered nodes if and only if a filter is applicable on the current script
• processing marked nodes goes away completely

• https://github.com/remarkjs/remark-directive?tab=readme-ov-file#use
• https://github.com/lebalz/ofi-blog/pull/27/commits
• lebalz/ofi-blog@b3fdffb
• lebalz/ofi-blog@30b8954
• lebalz/ofi-blog@a56ee21
• lebalz/ofi-blog@3807121
• lebalz/ofi-blog@b0ec35b

Add tests for all currently implemented remark plugins, following the unified() usage as described here.

This is not entirely trivial, because (a) the transformed result is not returned from the unified() call but passed as an input to a callback function, and (b) Jest seems to run into a TypeScript-related issue with unified (see error below).

Test suite failed to run

    Jest encountered an unexpected token

    Jest failed to parse a file. This happens e.g. when your code or its dependencies use non-standard JavaScript syntax, or when Jest is not configured to support such syntax.

    Out of the box Jest supports Babel, which will be used to transform your files into valid JS based on your Babel configuration.

    By default "node_modules" folder is ignored by transformers.

    Here's what you can do:
     • If you are trying to use ECMAScript Modules, see https://jestjs.io/docs/ecmascript-modules for how to enable it.
     • If you are trying to use TypeScript, see https://jestjs.io/docs/getting-started#using-typescript
     • To have some of your "node_modules" files transformed, you can specify a custom "transformIgnorePatterns" in your config.
     • If you need a custom transformation specify a "transform" option in your config.
     • If you simply want to mock your non-JS modules (e.g. binary assets) you can stub them out with the "moduleNameMapper" config option.

    You'll find more details and examples of these config options in the docs:
    https://jestjs.io/docs/configuration
    For information about custom transformations, see:
    https://jestjs.io/docs/code-transformation

    Details:

    /Users/silas/repos/teaching-website/node_modules/unified/index.js:2
    export {unified} from './lib/index.js'
    ^^^^^^

Implement a solution for providing downloadable resources, such as worksheets, exercise files, example data, test suites, project skeletons, etc.

Criteria

• File size is not a concern with regards to Git / GitHub (uses Git LFS, or files are not source-controlled / manually copied to webhost).
• There exists a well-designed component such as a sidebar or top-bar, where the available resources for that page are collected.

See PlantUML website.

The syntax might look something like this:

# A diagram
Here's a diagram:
```plantuml render
Bob->Alice : Hello!
``

where the plantuml render block is replaced with the SVG (or PNG/JPEG if need be) resulting from rendering its body with PlantUML:

Works:

  "creative-corner": {
    "markers": {
      "cc": 1
    },
    "mappings": [
      {"section": "index.md", "material": "/ScriptLandingPages/creative-corner.md"},
      {
        "section": "/Components-Gallery",
        "material": "/Components-Gallery"
      }
    ]
  }

Does not work properly; uses both index.mdx and index.[cc].mdx and creates directories 01-Komponentengalerie and Components-Gallery:

  "creative-corner": {
    "markers": {
      "cc": 1
    },
    "mappings": [
      {"section": "index.md", "material": "/ScriptLandingPages/creative-corner.md"},
      {
        "section": "/01-Komponentengalerie",
        "material": "/Components-Gallery"
      }
    ]
  }

The teach site is currently serving two target groups: teachers and students. It might be useful to have two distinct sites teach and learn, for teachers and students respectively. The former should contain the "complete" collection (including teacher-specific instructions, etc.), while the latter should be a reduced version containing only what's useful for the students.

Ideally, the learn site's script definition should be a function of the teach site's definition + markers. This might require for the marker system to be expanded to allow for marker exclusions. For instance, an article some-article.[gym,teachers].md should be included in the gym script for the teach site, but not for the learn site.

It would also be useful for each article on the teach site to provide a Go to Learn button, which changes to that same article in the learn site. Requirements for this would include:

• Article (i.e. component in article) contains logic to decide whether the button should be shown (when on teach) or hidden (when on learn).
• Article contains logic to decide not to show the button on teacher-only sites.

https://docusaurus.io/docs/search

:::DefList
  <dt>Some title</dt>
  <dd>Some text</dd>
  <dd>Some more text</dd>
::

or

:::DefList
:::DT
Some title
::DD
Some text
::DD
Some more text

Consider adding some basic smoke test-style e2e tests for each site, which:

• Open the site's home page
• Click each navbar link
• Navigate to a docs page by always clicking on the first tile

Add checks to pipeline (possibly only for main).

IntelliJ's proofreading feature is very superficial. Add some form of proofreading step to the local build process and/or the CI pipeline. Ideally, there should be a plugin that can detect typos, grammatical mistakes, etc. for multiple languages, and you can specify what language is used based on some folder or filename pattern.

@site/... imports work fine in React components and in .mdx files (thanks to intellij.config.js workaround for IntelliJ MDX plugin). However, they do not work in the docusaurus.config.ts and the whole builder part.

The @docusaurus/tsconfig file defines the @site path alias as follows:

"compilerOptions": {
  "paths": {
      "@site/*": ["./*"]
  },
}

It seems like that file doesn't apply to docusaurus.config.ts: Imports such as @site/src/builder/logger in docusaurus.config.ts are accepted (and even suggested) by the IDE, but during yarn run build, they yield the following error:

Cause: Cannot find module '@site/src/builder/logger'
Require stack:
- /Users/silas/repos/teaching-website/docusaurus.config.ts
    at loadFreshModule (/Users/silas/repos/teaching-website/node_modules/@docusaurus/utils/lib/moduleUtils.js:36:15)
    at loadSiteConfig (/Users/silas/repos/teaching-website/node_modules/@docusaurus/core/lib/server/config.js:35:62)
    ... 2 lines matching cause stack trace ...
    at async Command.start (/Users/silas/repos/teaching-website/node_modules/@docusaurus/core/lib/commands/start.js:44:19) {
  [cause]: Error: Cannot find module '@site/src/builder/logger'

Also note that the custom tsconfig.json file in the project root only applies for the IDE and is not used during compilation.

See: https://docusaurus.io/docs/markdown-features/tabs#query-string.

Rough syntax idea:

:::Tiles small
:::Tile The title; https://foo.bar/
The body of the tile

::Tile Another title; no_grow
Another tile body

::Tile Third tile

::Tile Fourth tile; https://bar.baz/; no_grow
One more body
:::

As implemented by #28

Sass support works fine in all components, with the docusaurus-plugin-sass and sass dependencies, the 'docusaurus-plugin-sass' plugin entry in docusaurus.config.ts, and the "types": ["docusaurus-plugin-sass"]addition intsconfig.json`.

However, Sass does not seem to take effect on src/css/styles.scss (for instance, variables are not resolved but used as plain strings instead). The file is currently renamed back to styles.css, and the customCss: ... entry in docusaurus.config.ts adjusted accordingly.

For instance, we can't yet use MDI shorthands such as :mdi[microsoft-windows] Admonitions titles:

:::insight[Interesting fact about Windows :mdi[microsoft-windows]]
Foobar.
:::

This limitation is most likely a result of the consumeDirectiveLabelChild() implementation remark-container-directives/plugin.ts. The same behavior can be observed with tab titles:

::::Tabs
  :::Tab[Windows :mdi[microsoft-windows]]{value="win"}
  Foo
  :::

  :::Tab[macOS :mdi[apple]]{value="macos"}
  Bar
  :::
::::