Metadata-Version: 2.5
Name: mkdocs-pseudocode-i18n
Version: 0.8.0
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 :: 3 - Alpha
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<0.9,>=0.8.0
Requires-Dist: pygments-lexer-pseudocode-i18n<0.9,>=0.8.0
Requires-Dist: pymdown-extensions>=10.0
Provides-Extra: dev
Requires-Dist: build>=1.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` files, published on Open VSX and Visual Studio Marketplace |

**Current version: 0.8.0.**
**Requires:** `pseudocode-i18n >= 0.8.0, < 0.9` and `pygments-lexer-pseudocode-i18n >= 0.8.0, < 0.9`.  
**License:** GNU GPL-3.0-or-later.

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

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

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

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 one source extension, `.pseudo`.

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

## 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 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:

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

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:

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

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

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