markers become filters

[SilasBerger]

• 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

[SilasBerger]

Here's what changes in comparison to the current description of mappings and filters in the README on main.

An excerpt of the scripts configs file <mySite>.scriptsConfigs.json for a site mySite might look as follows:

{
  "english": { # this object defines a script named "english"; its URL path will be /english
    "filters": { # filters definition (see below)
      "english": 0, # filter "english" has specificity 0 (the lower the number, the higher the precedence)
      "languages": 1 # filter "languages" has specificity 1
    },
    "mappings": [ # mappings definition
      # recursively copy the /General-Information directory from the material library to /01-General-Information in
      # the script 
      {"section": "/01-General-Information", "material": "/General-Information"},
      {"section": "/02-Units/01-Unit-1", "material": "/English/Units/Unit-1"},
      {"section": "/02-Units/02-Unit-2", "material": "/English/Units/Unit-2"}
    ]
  },
  "programming": {
    "filters": {
      "programming": 0
    },
    "mappings": [
      {"section": "/01-General-Information", "material": "/General-Information"},
      {
        # recursively copy the /Computer-Science/Programming/01-Introduction directory from the material library
        # to /02-Introduction-to-Programming in the script, but...
        "section": "/02-Introduction-to-Programming",
        "material": "/Computer-Science/Programming/01-Introduction",
        # ...from /Computer-Science/Programming/01-Introduction, ignore the file 04-Loops/03-do-while.mdx and the
        # entire "06-Exceptions" directory
        "ignore": ["04-Loops/03-do-while.mdx", "06-Exceptions"]
      }
    ]
  }
}

Assuming a material tree that looks as follows:

├── General-Information
│   ├── Required-Materials.[english]
│   │   ├── 01-Stationary.md
│   │   └── 02-Books.md
│   ├── index.md
│   ├── 01-Organizational-Matters.md
│   ├── 02-Class-Rules.md
│   ├── 02-Class-Rules.[languages].md
│   ├── 03-Semester-Agenda.[programming].md
│   └── 03-Semester-Agenda.[english].md
├── Digital-Tools
│   ├── word-processing.md
│   └── programming-environment.[programming].md 
├── English
│   └── Units
│       ├── Unit-1
│       │   └── ...
│       └── Unit-2
│           └── ...
└── Computer-Science
    ├── Programming
    │   ├── 01-Introduction
    │   │   ├── 01-Hello-World
    │   │   │   └── ...
    │   │   ├── 02-Variables
    │   │   │   └── ...
    │   │   ├── 03-Conditionals
    │   │   │   └── ...
    │   │   ├── 04-Loops
    │   │   │   ├── index.md
    │   │   │   ├── 01-for.mdx
    │   │   │   ├── 02-while.mdx
    │   │   │   └── 03-do-while.mdx
    │   │   ├── 05-Functions
    │   │   │   └── ...
    │   │   └── 06-Exceptions
    │   │       └── ...
    │   └── 02-Classes-and-Objects
    ├── Algorithms
    │   └── ...
    └── Networks
        └── ...

The final english script at /path/to/scripts/english will look as follows:

├── 01-General-Information  # explicitly mapped, include all non-marked contents
│   ├── Required-Materials  # include directory because it was marked with [languages]
│   │   ├── 01-Stationary.md
│   │   └── 02-Books.md
│   ├── index.md
│   ├── 01-Organizational-Matters.md
│   ├── 02-Class-Rules.md  # source file: 02-Class-Rules.[languages].md
│   └── 03-Semester-Agenda.md  # source file: 03-Semester-Agenda.[english].md
└── 02-Units  # explicitly mapped, include all non-marked contents
    ├── 01-Unit-1 
    │   └── ...
    └── 02-Unit-2
        └── ..

The final programming script at /path/to/scripts/programming will look as follows:

├── 01-General-Information
│   ├── index.md
│   ├── 01-Organizational-Matters.md
│   ├── 02-Class-Rules.md  # source file: 02-Class-Rules.md (unmarked)
│   └── 03-Semester-Agenda  # source file: 03-Semester-Agenda.[programming].md
├── # missing now: Digital-Tools (not mapped, would have been implicitly included as parent of marked child with filter [programming])
└── 02-Introduction-to-Programming  # explicitly mapped, include all non-marked contents 
    ├── 01-Hello-World
    │   └── ...
    ├── 02-Variables
    │   └── ...
    ├── 03-Conditionals
    │   └── ...
    ├── 04-Loops
    │   ├── index.md
    │   ├── 01-for.mdx
    │   ├── 02-while.mdx
    │   └── # missing: 03-do-while.mdx (ignored)
    ├── 05-Functions
    │   └── ...
    └──  # missing: 06-Exceptions (ignored)

[lebalz]

Question: why not using the frontmatter and the docusaurus tags?

• https://docusaurus.io/docs/create-doc#doc-tags
• example: doc with tags: https://ict.gbsl.website/textverarbeitung/word-1/ and the tag-page: https://ict.gbsl.website/tags/

[SilasBerger]

This might become relevant when working on a per-class basis.

[SilasBerger]

Note: marking a page as draft is supported through markdown frontmatter.

[SilasBerger]

Need to see whether the exact details are still correct. However, this issue is now becoming more important, since versioned pages will become a key use case for the first time:

• Many topics will be taught for the second time and may required changes
• Some pages / components will be migrated to use the new API now