mkdocs-pseudocode-i18n

Current version: 1.0.2. Release history: mkdocs-pseudocode-i18n changelog. License: GNU GPL-3.0-or-later.

Requirements and dependencies

• Python: 3.11 or newer (>=3.11).
• Pseudocode ecosystem: pseudocode-i18n >= 1.0.2, < 1.1 and pygments-lexer-pseudocode-i18n >= 1.0.2, < 1.1.
• MkDocs stack: mkdocs >= 1.6, < 2, pymdown-extensions >= 10.0 and PyYAML >= 6.0.
• These runtime dependencies are declared by the package and are installed automatically by pip.
• Building this repository's own documentation additionally uses the development documentation stack (including Material for MkDocs and mkdocs-graphviz); GitLab CI installs the Graphviz dot executable for those documentation jobs.

Rendered blocks inherit the core access-modifier vocabulary, including localized aliases plus universal English public, private and protected in all 14 source languages.

mkdocs-pseudocode-i18n lets you put multilingual educational pseudocode directly in MkDocs without maintaining separate highlighters for 14 languages: French, Spanish, Italian, Portuguese, German, Dutch, Danish, Swedish, Norwegian, Finnish, Greek, Ukrainian, Russian and English.

Use the same generic Markdown fence everywhere:

```pseudo
Si note >= 10 Alors:
    Afficher "Admis"
Sinon:
    Afficher "À revoir"
Fin
```

The plugin detects that this block is French, uses the shared Pygments lexer, preserves MathJax fragments, and keeps the original source available to the Material copy button.

Highlighted HTML is injected only after Markdown rendering. This prevents Python-Markdown/PyMdown extension combinations from escaping the generated <div class="highlight">…</div> and displaying it literally as text.

When you want to document the fence syntax itself, place the three-backtick pseudo fence inside a longer four-backtick Markdown fence. The plugin now respects that outer fence and leaves the inner ```pseudo / ``` markers literal instead of rendering them. The complete examples page demonstrates source → rendered output and Mermaid/Graphviz flowcharts in all 14 languages.

Shared Pseudocode ecosystem

The plugin deliberately does not duplicate the Tutor or editor execution model: step-by-step execution and synchronized flowchart state remain in pseudocode-i18n / pseudo-lsp; MkDocs stays a documentation renderer over the same shared language vocabulary.

MkDocs rendering uses the same current core vocabulary and Pygments lexer as the language-server/editor integrations. Markdown rendering remains independent from LSP transport while sharing the same language definitions. During one MkDocs build, the plugin reuses one configured PseudocodeLexer instance per source language instead of reconstructing the same lexer for every fenced block.

The shared vocabulary now includes project-module syntax (math, random, local .pseudo / .algo modules, and the localized local marker) plus universal alea() and entalea(a, b). Incomplete structural heads keep their syntax color; semantic validity remains the linter/LSP's responsibility.

Language directives

The canonical override is:

# language: fr

All four directive spellings are accepted:

# language: fr
# language fr
# lang: fr
# lang fr

In source code, # is the only comment/directive marker; // is integer division. In configuration, lang: is accepted as an alias for language:.

Why use it?

The plugin follows the same grammar as pseudocode-i18n, so your documentation accepts the same classroom-friendly forms as .pseudo/.algo files:

• automatic language detection;
• optional language directive (# language: fr canonically; language/lang, optional colon);
• Si ... Alors, Sinon Si, Sinon, optional FinSi and generic Fin;
• Répéter N fois and Répéter ... Jusqu'à;
• infinitive/imperative command synonyms such as Afficher / Affiche, Lire / Lis, Mostrar / Muestra, German Ausgeben / Gib aus, and localized equivalents;
• optional typed declarations with integer, float/real, string, boolean, array/list, dictionary, set and tuple;
• localized null values such as Vide, Vacío, Vuoto, Vazio, Leer and None;
• =, :=, arrows and normal arithmetic/comparison operators;
• membership operators including Dans, localized not in synonyms, ∈ and ∉;
• TeX fragments rendered through MathJax.

The language grammar is not duplicated in this project. It comes from pseudocode-i18n, and highlighting comes from pygments-lexer-pseudocode-i18n. Semantic linting and the native type system also belong to pseudocode-i18n; this MkDocs plugin renders code and does not redefine semantic rules.

Current rendering model

MkDocs rendering stays synchronized with the coordinated core and Pygments lexer.

• syntax highlighting consumes the current lexer categories, so declarations, constructors, constants, builtins and imports follow Python-equivalent semantic roles instead of a custom fixed palette;
• math, imported names and aliases are no longer flattened into keyword coloring;
• localized constructors are rendered as function definitions, and function/class declarations use their proper definition categories;
• all 14 languages, aliases and grammar changes come from the shared core/lexer rather than duplicated MkDocs rules;
• existing MathJax-in-strings, copy support, language-aware fences and flowchart features remain unchanged.

Actual colors continue to come from the active Pygments/MkDocs theme.

Install

python -m pip install mkdocs-pseudocode-i18n

Enable the plugin in mkdocs.yml:

plugins:
  - search
  - pseudocode

The plugin also injects a small, pseudocode-scoped style for Pygments Keyword.Constant tokens. This guarantees that localized constants such as Vide, Vrai and Faux remain visibly highlighted in every site using the plugin, both in normal pseudo fences and when a pseudo fence is shown literally inside a longer markdown fence. The plugin marks only those Markdown examples that actually contain pseudocode, so unrelated code blocks are not recolored. With Material for MkDocs, the rule reuses --md-code-hl-constant-color; other themes receive a light/dark fallback. Sites can override only this pseudocode constant color with --pseudocode-constant-color. No extra CSS is required for the default behavior.

Generated per-language references also include the complete current range-loop/step vocabulary and localized Do/Faire/... forms, so documentation fences and reference pages stay aligned with the shared parser and lexer.

The same scoped fallback now covers Pygments Operator.Word: localized logical operators such as French ET, OU, NON and OUEX keep the Python-equivalent token role from the shared lexer and remain visibly colored even when the surrounding MkDocs theme does not style .ow. Material reuses --md-code-hl-keyword-color; other themes receive light/dark fallbacks. Sites can override this with --pseudocode-logical-operator-color.

For Material for MkDocs, the usual highlighting extensions work well:

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.arithmatex

One fence for every language

The preferred fence is simply:

```pseudo
...
```

or equivalently:

```pseudocode
...
```

Français

```pseudo
age est un entier
absent = Vide

Si age >= 18 Alors:
    Écrire "Majeur"
Sinon:
    Afficher "Mineur"
Fin
```

Español

```pseudo
edad es un entero
ausente = Vacío

Si edad >= 18 Entonces:
    Escribir "Adulto"
Sino:
    Mostrar "Menor"
Fin
```

Italiano

```pseudo
eta è un intero
assente = Vuoto

Se eta >= 18 Allora:
    Mostra "Maggiorenne"
Altrimenti:
    Mostra "Minorenne"
Fine
```

Português

```pseudo
idade é um inteiro
ausente = Vazio

Se idade >= 18 Então:
    Mostrar "Adulto"
Senão:
    Mostrar "Menor"
Fim
```

Deutsch

```pseudo
alter ist eine Ganzzahl
fehlend = Leer

Wenn alter >= 18 Dann:
    Ausgeben "Volljährig"
Sonst:
    Ausgeben "Minderjährig"
Ende
```

English

```pseudo
age is an integer
missing = None

If age >= 18 Then:
    Display "Adult"
Else:
    Display "Minor"
End
```

Every Usage topic is generated separately for the 14 languages in the project order French → Spanish → Italian → Portuguese → German → Dutch → Danish → Swedish → Norwegian → Finnish → Greek → Ukrainian → Russian → English.

Force a language only when needed

Normally, let the plugin detect the language. If a short or ambiguous block needs help, add the universal directive inside the block:

```pseudo
# language: es
x = 2
Mostrar x
```

You can also force a language with an explicit fence alias:

pseudo-fr / pseudocode-fr
pseudo-es / pseudocode-es
pseudo-it / pseudocode-it
pseudo-pt / pseudocode-pt
pseudo-de / pseudocode-de
pseudo-en / pseudocode-en

These aliases are explicit overrides, not filename extensions. The shared ecosystem uses two equivalent source extensions, .pseudo and .algo.

Shared project configuration

mkdocs-pseudocode-i18n uses the same pseudocode.config.yml as the core and lexer:

language: auto
fallback_language: fr

mkdocs:
  inject_mathjax: true

Resolution for a generic pseudo fence is:

1. explicit fence alias (pseudo-es, for example);
2. language directive inside the block (# language: xx canonically; language/lang, optional colon);
3. configured language when it is not auto;
4. automatic detection from the block content;
5. fallback_language.

You can still force a whole MkDocs site:

plugins:
  - pseudocode:
      language: es

A directive inside a generic block still has priority over that configured default, matching the current core precedence rules.

Custom synonyms

Language vocabulary remains data-driven. For example:

languages:
  fr:
    keywords:
      display:
        add:
          - Montrer

Then this becomes highlightable without changing plugin code:

```pseudo
Montrer "Bonjour"
```

The same override can be stored in the shared pseudocode.config.yml so the parser, formatter, lexer and MkDocs integration agree.

Types, collections and null values

```pseudo
notes est un tableau
profil est un dictionnaire
vus est un ensemble
position est un tuple
message est une chaîne
absence = Vide

Si note ∉ notes Alors:
    Afficher "Nouvelle note"
Fin
```

Vide means the same semantic null value as Python None. It is distinct from empty collections: [] is an empty list, {} an empty dictionary, and an empty set corresponds to set() / the localized set constructor supported by the core.

Repetition

```pseudo
Répéter 5 fois:
    Afficher "Bonjour"
Fin
```

and:

```pseudo
Répéter:
    n = n + 1
Jusqu'à n >= 10
Fin
```

are highlighted with the same structural grammar understood by the core transpiler.

MathJax inside pseudocode

TeX fragments remain MathJax-processable:

```pseudo
Si \Delta \geq 0 Alors:
    Afficher $x^2$
    Afficher '"$\geq$"'
Fin
```

Explicit $...$ fragments are also rendered inside pseudocode strings. The recommended form is Afficher '"$\geq$"'; the fully MathJax form Afficher '$\text{"}\geq\text{"}$' is supported as well. Escaped or unmatched dollar signs remain literal text.

The plugin injects MathJax 3 only when requested and when a MathJax script is not already present on the page.

Python transpilation and automatic flowcharts

Bidirectional Python transpilation lives in the semantic core. For documentation, this plugin can turn pseudocode directly into either a Mermaid or a Graphviz flowchart fence. The semantic graph and geometry are generated by pseudocode-i18n; MkDocs only renders the returned Mermaid/DOT source.

Both forms are equivalent:

```pseudo flowchart
Si x > 0 Alors:
    Afficher "positif"
Sinon:
    Afficher "négatif"
Fin
```

```pseudo mermaid
Si x > 0 Alors:
    Afficher "positif"
Sinon:
    Afficher "négatif"
Fin
```

Graphviz uses the same Pseudocode and the same core semantic graph:

```pseudo graphviz
# language: fr
Pour i de 1 à 3:
    Afficher i
Fin
```

Explicit language fences also work, for example pseudo-es mermaid and pseudo-es graphviz. flowchart remains a compatibility alias for Mermaid. The plugin emits the canonical Mermaid or Graphviz source from pseudocode-i18n: Mermaid carries the shared validated-loop-attached-edges-v22 ELK policy, while Graphviz carries deterministic fixed positions with WEST loop-back / EAST exit routing. Mermaid is handled by the site's Mermaid fence and Graphviz by the mkdocs_graphviz MkDocs plugin. For Graphviz, mkdocs-graphviz is the renderer of record: configured graph, node and edge attributes take priority over the core's ordinary DOT defaults, including Light/Dark, page-level and per-graph settings. The integration follows the same generic Graphviz attributes that mkdocs-graphviz sends as -G, -N and -E defaults. Typography is fed back into the shared core before fixed positions are generated, while Graphviz itself is used to measure the effective rendered node bounds with the complete configuration (font family/size, shape, margins, fixed dimensions and other native attributes). Adjacent fixed Y ranks are then moved apart only when those measured bounds plus the effective edge-label line no longer fit the normal spacing; this keeps large 40–50 pt (and larger) labels clear without changing branch alignment or loop attachment ranks. WEST/EAST loop waypoints are likewise moved only when necessary to clear the real node bounds. Generated Graphviz SVGs keep their natural renderer size inside a horizontally scrollable container instead of being forced back to the article width, so increasing node.fontsize / edge.fontsize remains visibly effective. For documentation rendering, edge labels are painted after nodes by default (outputorder=nodesfirst) so large Oui / Non labels cannot disappear underneath node fills; an explicit mkdocs_graphviz.common.graph.outputorder still has priority. Labels, stable IDs, fixed positions and invisible routing semantics remain structural Pseudocode data. Normal documentation builds do not invoke Chromium/Mermaid CLI for Mermaid.

For example, the core can transpile:

Si x ∉ valeurs Alors:
    Afficher "Absent"
Fin

to Python:

if x not in valeurs:
    print("Absent")

and can export the same pseudocode as a Mermaid or Graphviz flowchart/algorigram. The documentation site shows both engines side by side in Pseudocode/Mermaid/Graphviz tabs.

Copying source

Rendered blocks embed the original pseudocode source in a base64 data attribute. The small browser hook included by the plugin lets Material's copy action copy the original pseudocode, not the MathJax-modified HTML representation.

Development

yarn setup
yarn bfc

yarn setup prefers editable sibling checkouts of:

../pseudocode-i18n
../pygments-lexer-pseudocode-i18n

when present. This is the recommended development layout for the coordinated ecosystem.

yarn bfc performs version synchronization, version checks, Ruff, pytest, documentation synchronization/checking, a strict MkDocs build, and Python package build.

Documentation is part of every project change. The documentation tree is deliberately human-editable: yarn docs:sync preserves existing pages, while yarn docs:regen explicitly reseeds site/index.md and the per-language pages from this README and the core language YAML files. Tests validate structure and required rendering examples rather than exact prose, so translations can be improved manually without fighting the build.

Versioning

package.json is the single source of truth for the project version. yarn version:sync propagates that version to pyproject.toml, mkdocs_pseudocode_i18n/__init__.py and this README.

MkDocs pages use the placeholder:

__MKDOCS_PSEUDOCODE_I18N_VERSION__

which is replaced at documentation build time from package.json by the MkDocs version hook.

Releases

A normal push updates main and GitLab Pages without creating a release.

A release workflow can stamp a version/tag, build the package, publish to PyPI through the configured GitLab Trusted Publishing pipeline, then create the GitLab Release.

See the full documentation for the exact project workflow.

License

GNU GPL-3.0-or-later.

AUTRES PROJETS de ce développeur

The Pseudocode ecosystem is designed as several small projects sharing one grammar instead of duplicating it:

• pseudocode-i18n — parser, formatter, executor/Python transpiler, language detection and Mermaid/Graphviz flowcharts;
• pygments-lexer-pseudocode-i18n — Pygments syntax highlighting using the shared multilingual definitions;
• vscode-pseudocode-i18n — editor integration for .pseudo/.algo files and the Open VSX ecosystem.

See the repositories for the rest of the developer's open-source projects.

Syntax highlighting preserves compound localized type aliases supplied by the shared lexer: for example, French n-uplet is highlighted as a type without reserving the identifiers n or uplet on their own.