Metadata-Version: 2.5
Name: mkdocs-pseudocode-i18n
Version: 1.0.2
Summary: Multilingual educational pseudocode blocks for MkDocs with automatic language detection, Pygments and MathJax
Project-URL: Homepage, https://rod2ik.gitlab.io/mkdocs-pseudocode-i18n/
Project-URL: Documentation, https://rod2ik.gitlab.io/mkdocs-pseudocode-i18n/
Project-URL: Repository, https://gitlab.com/rod2ik/mkdocs-pseudocode-i18n
Project-URL: Issues, https://gitlab.com/rod2ik/mkdocs-pseudocode-i18n/-/issues
Author: Rod2ik
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: education,i18n,mathjax,mkdocs,pseudocode,pygments
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Documentation
Classifier: Topic :: Education
Requires-Python: >=3.11
Requires-Dist: mkdocs<2,>=1.6
Requires-Dist: pseudocode-i18n<1.1,>=1.0.2
Requires-Dist: pygments-lexer-pseudocode-i18n<1.1,>=1.0.2
Requires-Dist: pymdown-extensions>=10.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mkdocs-graphviz<3,>=2.0.2; extra == 'dev'
Requires-Dist: mkdocs-material>=9.6; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

# mkdocs-pseudocode-i18n

| Resource | Link | Purpose |
| --- | --- | --- |
| **mkdocs-pseudocode-i18n — repository** | [gitlab.com/rod2ik/mkdocs-pseudocode-i18n](https://gitlab.com/rod2ik/mkdocs-pseudocode-i18n) | Render multilingual pseudocode directly in MkDocs pages |
| **mkdocs-pseudocode-i18n — documentation** | [rod2ik.gitlab.io/mkdocs-pseudocode-i18n](https://rod2ik.gitlab.io/mkdocs-pseudocode-i18n/) | Complete user and developer documentation |
| **pseudocode-i18n** | [gitlab.com/rod2ik/pseudocode-i18n](https://gitlab.com/rod2ik/pseudocode-i18n) | Shared grammar, language detection, formatter, Python transpiler and flowcharts |
| **pygments-lexer-pseudocode-i18n** | [gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n](https://gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n) | Python-like Pygments highlighting driven by the same language definitions |
| **vscode-pseudocode-i18n** | [gitlab.com/rod2ik/vscode-pseudocode-i18n](https://gitlab.com/rod2ik/vscode-pseudocode-i18n) | VS Code editing experience for `.pseudo` and `.algo` files, published on Open VSX and Visual Studio Marketplace |
| **pseudocode-i18n-languageserver** | [gitlab.com/rod2ik/pseudocode-i18n-languageserver](https://gitlab.com/rod2ik/pseudocode-i18n-languageserver) | Shared LSP intelligence for Kate, Neovim, Spyder and other editor integrations |
| **thonny-pseudocode-i18n** | [gitlab.com/rod2ik/thonny-pseudocode-i18n](https://gitlab.com/rod2ik/thonny-pseudocode-i18n) | Thonny 5 adapter using the same LSP intelligence, snippets, navigation and flowcharts |

**Current version: 1.0.2.**
**Release history:** [mkdocs-pseudocode-i18n changelog](https://rod2ik.gitlab.io/mkdocs-pseudocode-i18n/reference/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:

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

```text
# language: fr
```

All four directive spellings are accepted:

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

```bash
python -m pip install mkdocs-pseudocode-i18n
```

Enable the plugin in `mkdocs.yml`:

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

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

## One fence for every language

The preferred fence is simply:

````markdown
```pseudo
...
```
````

or equivalently:

````markdown
```pseudocode
...
```
````

### Français

````markdown
```pseudo
age est un entier
absent = Vide

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

### Español

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

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

### Italiano

````markdown
```pseudo
eta è un intero
assente = Vuoto

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

### Português

````markdown
```pseudo
idade é um inteiro
ausente = Vazio

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

### Deutsch

````markdown
```pseudo
alter ist eine Ganzzahl
fehlend = Leer

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

### English

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

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

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

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

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

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

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

Then this becomes highlightable without changing plugin code:

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

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

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

and:

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

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

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

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

```text
Si x ∉ valeurs Alors:
    Afficher "Absent"
Fin
```

to Python:

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

```bash
yarn setup
yarn bfc
```

`yarn setup` prefers editable sibling checkouts of:

```text
../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:

```text
__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](https://gitlab.com/rod2ik/pseudocode-i18n)** — parser, formatter, executor/Python transpiler, language detection and Mermaid/Graphviz flowcharts;
- **[pygments-lexer-pseudocode-i18n](https://gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n)** — Pygments syntax highlighting using the shared multilingual definitions;
- **[vscode-pseudocode-i18n](https://gitlab.com/rod2ik/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.
