La démonstration intégrale

§1.1Marques en ligne

L’analyse de l’emphase est compatible CJK : le gras se referme même contre une ponctuation chinoise — **报文。**同时 se rend 报文。同时, et non comme des astérisques littéraux. L’italique, le barré et le code en ligne fonctionnent comme d’habitude ; avec l’option gemoji, un raccourci tel que :sparkles: se rend ✨. Les caractères à l’intérieur du code en ligne ne participent à aucune analyse : les accents graves sont donc la voie sûre pour montrer de la syntaxe — **, $…$ et > [!note] s’affichent tous littéralement. Pour montrer un astérisque dans la prose, échappez-le — *comme ceci* reste tel quel.

§1.2Wikiliens

Avec l’option wikilinks activée, les liens [[à doubles crochets]] se résolvent contre la collection de notes comme un wiki s’y attend : par id (design-tokens), par alias (boundaries atteint la note dont l’id est three-way-split), avec un libellé (le guide Premiers pas). Une cible qui ne se résout à rien se rend comme un lien mort marqué au lieu de faire échouer le build — et la CLI check-wikilinks du moteur la signale en CI, là où la pourriture des liens doit se voir.

§1.3Tableaux : défilement en large, cartes en étroit

Un tableau de six colonnes ou plus doit se replier, une ligne par carte, dans un conteneur étroit, au lieu d’écraser chaque cellule sur deux caractères. Ce tableau de sept colonnes est à la fois l’aide-mémoire des variantes de callout et un test en direct de ce repli (réduisez la fenêtre à une largeur de téléphone) :

Les titres par défaut sont en anglais ; un site remplace le jeu entier par l’option calloutLabels de siteMarkdown, par exemple calloutLabels: { tip: 'Intuition', warn: 'Avertissement' }. Un titre écrit dans la syntaxe de citation (> [!tip] Mon titre) a toujours le dernier mot.

§2.1Callouts : trois écritures

D’abord, la syntaxe de citation à la Obsidian/GitHub (disponible avec callouts: true, y compris dans les fichiers Markdown purs) :

Le marqueur de repli d’Obsidian est honoré — > [!note]- se rend replié, > [!note]+ déplié :

Deuxième écriture, le composant du paquet en MDX (astro-inkstone/components/Callout.astro, importé par chemin). Sans title, il affiche le libellé par défaut de sa variante — le même que celui de la syntaxe de citation :

Troisième écriture, le HTML brut, les six variantes d’un seul tenant (en correspondance une à une avec les règles .callout de base.css) :

§2.2Mathématiques

Les formules en ligne se glissent dans le texte : la profondeur optique s’écrit $\tau = \int \kappa \rho \, \mathrm{d}s$. Les formules hors texte prennent la forme à trois lignes ($$ seuls sur leur ligne) — le garde-fou rejette la forme sur une seule ligne, qui se rendrait silencieusement comme une petite formule en ligne :

Le fond des formules est délibérément un autre papier que celui du corps, et il change avec le thème. Au passage, échappez les prix en dollars dans la prose : ce café coûte $3.

§3.1Cadres de code

Une clôture avec title="…" reçoit une barre de titre au nom du fichier ; le bouton de copie dans le coin vaut pour tout le site. Les annotations de ligne [!code ++] / [!code --] se rendent en fonds de diff :

def build_pipeline(opts):
    plugins = [remark_math]  
    plugins = [remark_gemoji, remark_math]  
    return assemble(plugins, guard=opts.guard)

Un cadre marqué collapse démarre replié et ne prend de place qu’une fois ouvert — parfait pour les longs fichiers de configuration :

site:
  markdown:
    numbering: chapters
    math: true
    codeFrame: true
    mermaid: true
    callouts: true
    wikilinks: true
  styles:
    - astro-inkstone/styles/tokens.css
    - astro-inkstone/styles/base.css

La coloration bi-thème vient de shiki, qui émet les deux jeux de couleurs d’un coup ; base.css en choisit un par data-theme, en un seul endroit — aucun bras de fer de spécificité.

§3.2Diagrammes mermaid

Une clôture ```mermaid ne laisse qu’un emplacement réservé au moment du build ; le moteur de rendu ne se charge dynamiquement que sur les pages qui portent un diagramme (les autres ne paient rien), et il re-rend quand le thème bascule :

flowchart LR
  A["astro-inkbrush<br/>moteur : édition / dialecte / garde-fou"] --> C["votre site<br/>identité / routage / déploiement"]
  B["astro-inkstone<br/>papier : tokens / styles / pipeline"] --> C
  A -. un seul dialecte partagé .-> B

§3.3Les extras GFM

Les listes de tâches et les notes de bas de page arrivent avec GFM :

• tokens importés
• base.css importé
• palette d’identité surchargée

Une affirmation qui mérite sa source reçoit une note de bas de page.¹

§4.1Ce que le garde-fou rejette sur cette page

Que cette page se construise démontre en soi que tout ce qui précède est bien formé. Les écritures suivantes feraient échouer le build sur-le-champ (essayez-en une, puis npm run build) :

• une marque d’emphase qui ne peut pas s’apparier, comme un ** laissé ouvert en fin de ligne ;
• le $$x$$ sur une seule ligne (employez la forme à trois lignes) ;
• les titres numérotés à la main — écrire le titre de cette section ## 9. Ce que le garde-fou… entrerait en collision avec la numérotation faite au build, et serait signalé ;
• MDX évaluant les accolades de votre prose : {0,1,2,3} se rendrait comme un simple 3, le garde-fou exige donc la forme échappée {0,1,2,3} ;
• une formule que KaTeX ne sait pas rendre (le garde-fou re-rend chaque formule en mode strict au lieu de laisser partir du texte d’erreur rouge).