mkdocs-pseudocode-i18n

Current version: 0.9.1. Requires: pseudocode-i18n >= 0.9.1, < 0.10 and pygments-lexer-pseudocode-i18n >= 0.9.1, < 0.10.
License: GNU GPL-3.0-or-later.

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 flowcharts in all 14 languages.

0.9 LSP ecosystem

Version 0.9 aligns MkDocs rendering with the shared 0.9 core and lexer used by the new language server. Markdown rendering remains independent from editor LSP transport while sharing the same language definitions.

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.

0.9.1 — rendering synchronized with the complete 0.9 language

Version 0.9.1 documents the complete 0.9.1 Pseudocode surface rendered by MkDocs:

• 14 generated languages and Unicode identifiers through the shared Pygments/core registry;
• .pseudo / .algo ecosystem compatibility while Markdown continues to use pseudo, pseudocode and explicit pseudo-xx fences;
• complete localized OOP vocabulary, including universal-English public / private / protected aliases;
• local, alea() and entalea(a, b) highlighting and examples;
• structural-head highlighting preserved for incomplete statements so documentation matches the editor experience;
• MathJax-aware fragments inside Pseudocode code blocks and quoted strings;
• pseudo flowchart / pseudo mermaid fences, localized flowchart labels and Material-compatible copy behavior;
• semantic linting, type contracts, local-module resolution and runtime errors remain core responsibilities and are documented here without being reimplemented by the MkDocs plugin.

The plugin therefore remains a rendering layer over the same language definition used by CLI, LSP, VS Code and Thonny.

0.8 Unicode, 14 languages and reliable MathJax

Version 0.8 consumes all 14 data-driven language definitions from the coordinated core/lexer stack. Greek and Cyrillic identifiers are highlighted as normal identifiers, and every Usage topic is generated separately for every language with real conditions, loops, functions, classes and reference tables.

Math inside pseudocode blocks no longer relies on unrestricted MathJax scanning of <pre><code> elements. The plugin stores each math fragment explicitly, marks only those placeholders for MathJax processing, and renders them with MathJax's native typesetPromise() document pipeline. Without $...$, it accepts a deliberately compact safe set including common symbols, \displaystyle (including a following supported fragment), \frac, \dfrac, \sqrt, and simple powers written with ^ or **. More complex TeX remains explicit with $...$. Explicit dollar-delimited fragments are also recognized inside quoted strings, so forms such as Afficher '"$\geq$"' render the mathematical symbol without giving up normal string quoting. Because the formulas stay inside MathJax's document pipeline, CommonHTML glyph styles are managed by MathJax itself and symbols, roots, fractions and powers remain visible inside pseudocode code blocks.

The language grammar is still not duplicated in this project: supported pseudo-xx fences are discovered from pseudocode-i18n.

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.

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 core 0.6 semantics.

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 now turn pseudocode directly into a Mermaid flowchart fence, which lets the Mermaid support already configured in MkDocs render the diagram as SVG in the page.

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
```

Explicit language fences also work, for example pseudo-es flowchart. The plugin emits standard Mermaid source and deliberately relies on the site's existing Mermaid renderer; it does not invoke Chromium or Mermaid CLI during a normal MkDocs build. The plugin also keeps the Mermaid container/SVG background transparent unless the site deliberately overrides it.

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 flowchart/algorigram. You can then embed the Mermaid output in any MkDocs setup that supports Mermaid.

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. site/index.md is generated from this README, and the per-language reference pages are generated from the core language YAML files.

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 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.