Techniques avancées

Configuration avancée

Lorsque le fichier de configuration config/mkdocs.yml devient trop grand, il peut être avantageux de le diviser et d’utiliser l’héritage

Pour le site que vous voyez, la configuration est composée de deux fichiers. Un fichier de base avec une configuration “standard” pour les sites d’éducation :

config/base.yml

docs_dir: '../docs/'
site_dir: '../public/'

theme:
  name: material
  language: 'fr'
  font:
    text: 'Roboto'
    code: 'IBM Plex Mono'
  custom_dir: '../overrides/'
  icon:
    logo: material/school 
  favicon: 'assets/images/favicon.ico'
  features:
    - content.code.annotate

markdown_extensions:
  admonition: {}
  extra: {}
  smarty:
      smart_angled_quotes: true
      substitutions:
        left-angle-quote: "&laquo;&#xA0;"
        right-angle-quote: "&#xA0;&raquo;"
  mkdcomments: {}
  footnotes: {}
  codehilite: {}
  pymdownx.arithmatex:
    generic: true
  pymdownx.betterem:
    smart_enable: all
  pymdownx.tabbed: {}
  pymdownx.highlight: {}
  pymdownx.caret: {}
  pymdownx.critic: {}
  pymdownx.details: {}
  pymdownx.keys: {}
  pymdownx.emoji:
    emoji_index: !!python/name:materialx.emoji.twemoji
    emoji_generator: !!python/name:materialx.emoji.to_svg
  pymdownx.inlinehilite: {}
  pymdownx.magiclink: {}
  pymdownx.mark: {}
  pymdownx.smartsymbols: {}
  pymdownx.superfences: {}
  pymdownx.tasklist:
    custom_checkbox: true
  pymdownx.tilde: {}
  mdx_math: {}
  attr_list: {}
  md_in_html: {}

extra_css:
  - 'stylesheets/extra.css'

extra_javascript:
  - javascripts/mathjax.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

plugins:
  search: {}
  include-markdown:
    opening_tag: '{!'
    closing_tag: '!}'
  awesome-pages: {}
  macros: {}
  mkdocs-simple-hooks:
    hooks:
      on_pre_build: "hooks:on_pre_build"

Et un fichier mkdocs.yml qui hérite du fichier de base et qui configure les paramètres spécifiques au site

config/mkdocs.yml

INHERIT: base.yml
site_url: https://heia-fr.github.io/mkdocs-edu-howto/
site_name: Création de sites web pour l'enseignement
site_description: Création de sites web pour l'enseignement
copyright: "Copyright &copy; 2022 Haute école d'ingénierie et d'architecture of Fribourg"

repo_url: https://github.com/heia-fr/mkdocs-edu-howto
repo_name: heia-fr/mkdocs-edu-howto
edit_uri: ""

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/heia-fr/mkdocs-edu-howto
    - icon: fontawesome/brands/dev
      link: https://dev.to/supcik

Sites multilangues

Si vous souhaitez que votre site soit disponible dans plusieurs langues, vous pouvez utiliser le plugin mkdocs-static-i18n. Ce plugin a été testé et fonctionne bien avec les techniques décrites dans ce site, mais les détails concernant son utilisation dépassent le cadre de ce site.

Et bien d’autres…

Le thème Material for MkDocs ainsi que les nombreux plugins pour mkdocs évoluent constamment pour offrir une meilleure expérience utilisateur. Nous vous invitons à étudier la documentation et les nombreuses publications sur Internet pour améliorer votre site web.