mkdocs-pseudocode-i18n

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

mkdocs-pseudocode-i18n lets you put multilingual educational pseudocode directly in MkDocs without maintaining separate highlighters for French, Spanish, Italian, Portuguese, German 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 six languages.

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 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.7 typed/OOP and data-driven language integration

Version 0.7 consumes the structured language model from the coordinated core/lexer stack. MkDocs therefore highlights typed function and method signatures, localized constructors, inheritance syntax, self/this, and public / protected / private modifiers without duplicating semantic rules.

The plugin no longer carries a fixed six-language lexer table: explicit fences such as pseudo-fr or a future pseudo-nl are derived from the languages discovered by pseudocode-i18n. Adding a language remains a data/generation operation rather than a plugin-code change.

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

The documentation deliberately presents languages in the project order French → Spanish → Italian → Portuguese → German → 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 one source extension, .pseudo.

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

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