Configuration

Options de thème

color_mode définit uniquement le mode initial. Les visiteurs peuvent le modifier avec l'en-tête basculer, et leur choix est stocké dans localStorage.

toc décide où va le sommaire construit à partir des titres de la page. auto le place dans la colonne de droite quand la fenêtre laisse la place à une troisième colonne, et sous le titre de la page sinon, où il devient un bloc dépliable que le lecteur ouvre plutôt qu'une liste posée entre le titre et le premier paragraphe. expanded le garde dans le flux et hors de la colonne, collapsed en fait un bloc dépliable, et hidden — ou false — le supprime.

Icônes

La navigation dans l'en-tête, le contrôle du mode couleur et le bouton de retour en haut utilisent le SVG en ligne. à partir d’un jeu d’icônes. octicons est la valeur par défaut ; choisissez les icônes Lucide avec :

theme:
  name: primer
  icon: lucide

Les deux ensembles sont inclus dans le thème, donc aucune des deux options n'ajoute de requête CDN. Icône la sélection s'applique uniquement aux contrôles HTML du thème. Le sélecteur de langue utilise toujours un globe Octicon. Syntaxe des icônes Markdown et tiers arbitraires les packs d'icônes ne sont délibérément pas pris en charge.

Polices

Les polices sont opt-in : le thème ne demande pas de CDN de police par défaut. Définir le texte et familles de codes indépendamment, puis pointez source vers une feuille de style externe ou un fichier CSS dans docs_dir :

theme:
  name: primer
  font:
    text: 'Inter, sans-serif'
    code: '"JetBrains Mono", monospace'
    source: https://fonts.googleapis.com/css2?family=Inter:wght@400;600&family=JetBrains+Mono&display=swap

Pour un site auto-hébergé, mettez les fichiers de polices et une feuille de style dans docs_dir, puis utilisez un chemin source relatif :

theme:
  name: primer
  font:
    text: 'Atkinson Hyperlegible, sans-serif'
    code: 'Atkinson Hyperlegible Mono, monospace'
    source: fonts/fonts.css

@font-face {
  font-family: "Atkinson Hyperlegible";
  src: url("AtkinsonHyperlegible-Regular.woff2") format("woff2");
  font-display: swap;
}

Le navigateur met normalement ces fichiers en cache. L'auto-hébergement évite un tiers demande et maintient le site utilisable hors ligne une fois ses actifs mis en cache.

Dispositions de droite à gauche

Définissez direction: rtl pour un document s'écrivant de droite à gauche. Le thème met dir="rtl" sur l'élément HTML racine et reflète son en-tête, sa barre latérale, sa navigation mobile, pagination, pied de page, menus et contrôles avec propriétés CSS logiques. Coder et les diagrammes restent intentionnellement de gauche à droite.

theme:
  name: primer
  direction: rtl

La direction est un paramètre à l’échelle du site ; le thème ne le déduit pas d'une page ou langue locale.

Ancres de titre

Pour obtenir l'ancre de survol de GitHub à côté de chaque en-tête, activez l'extension toc avec un permalien principal qui porte la classe anchor de Primer :

markdown_extensions:
  - toc:
      permalink: ""
      permalink_class: anchor
      permalink_leading: true
      permalink_title: Permanent link

Le thème dessine l'octicône lui-même, donc permalink est défini sur une chaîne vide plutôt que le true habituel. Cela compte bien plus que l'apparence : le plugin de recherche de MkDocs ne le fait pas supprimez les glyphes de permalien, de sorte qu'un ¶ apparaîtrait autrement dans vos résultats de recherche.

Sans cette configuration, le permalien fonctionne toujours, il s'affiche simplement sous la forme d'un simple glyphe. que l'octicon.

Mise en évidence de la syntaxe

Les couleurs des codes proviennent des variables prettylights de Primer, elles suivent donc les valeurs actives. mode couleur automatiquement. Aucun style Pygments ne doit être sélectionné :

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences

Les wrappers .highlight et .codehilite sont stylés, donc codehilite fonctionne également.

Le thème ajoute un bouton de copie à chaque bloc Pygments .highlight. Il copie le source visible et annonce si l’opération du presse-papiers a réussi. Blocs rendus par des plugins, tels que Mermaid et Vega-Lite, sont intentionnellement exclus.

Commandes de navigation

Après un défilement de 400 pixels, un bouton de retour en haut apparaît en bas à droite de la page. Il renvoie le visiteur au début du document et se déplace focus clavier sur le lien du titre du site. Le mouvement est instantané lorsque le visiteur a demandé une réduction des mouvements.

Extensions de démarque

Aucun de ces éléments n'est requis, mais le thème propose un style qui ne rapporte qu'une seule fois. ils sont sur :

markdown_extensions:
  - admonition   # !!! note blocks, colored with Primer's alert palette
  - def_list
  - footnotes
  - tables
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tilde

admonition est celui qui mérite d'être signalé : l'extension émet du balisage et aucun CSS qui lui est propre, et @primer/css n'a pas non plus de règle pour cela, donc un style sans style l'avertissement est une surprise courante. Le thème comble cette lacune — voir les exemples.

CSS et JavaScript personnalisés

extra_css est chargé après chaque feuille de style expédiée par le thème, afin que vos règles l'emportent sans avoir besoin de !important :

extra_css:
  - css/overrides.css
extra_javascript:
  - js/site.js
  # MkDocs 1.5+ also takes the mapping form.
  - path: js/chart.js
    type: module

Styling décrit quoi y mettre : les variables de mise en page propres au thème, et pourquoi une redéfinition d'un jeton de couleur Primer dans :root est ignorée alors que la même règle sous deux sélecteurs d'attribut s'applique.

extra_javascript est émis à la fin de <body>, après le thème propre scripts.

Modifier les liens

Le pied de page renvoie au fichier source lorsque repo_url et edit_uri sont définis :

repo_url: https://github.com/you/your-project
edit_uri: edit/main/docs/