Configuração

Opções de tema

color_mode define apenas o modo inicial. Os visitantes podem alterá-lo com o cabeçalho alternam e sua escolha é armazenada em localStorage.

toc decide para onde vai o sumário construído a partir dos títulos da página. auto o coloca na coluna da direita quando a janela comporta uma terceira coluna, e sob o título da página caso contrário, onde é um bloco que o leitor abre em vez de uma lista entre o título e o primeiro parágrafo. expanded o mantém no fluxo e fora da coluna, collapsed o transforma num bloco que o leitor abre, e hidden — ou false — o omite.

Ícones

A navegação do cabeçalho, o controle do modo de cor e o botão voltar ao topo usam SVG embutido de um conjunto de ícones. octicons é o padrão; escolha ícones Lucide com:

theme:
  name: primer
  icon: lucide

Ambos os conjuntos estão incluídos no tema, portanto nenhuma opção adiciona uma solicitação CDN. Ícone a seleção se aplica apenas aos controles HTML do tema. O seletor de idioma sempre usa um globo Octicon. Sintaxe do ícone Markdown e terceiros arbitrários pacotes de ícones não são deliberadamente suportados.

Fontes

As fontes são opcionais: o tema não solicita um CDN de fonte por padrão. Definir texto e codifique famílias de forma independente e aponte source para uma folha de estilo externa ou um arquivo CSS em 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

Para um site auto-hospedado, coloque os arquivos de fonte e uma folha de estilo em docs_dir e, em seguida, use um caminho de origem relativo:

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;
}

O navegador armazena esses arquivos em cache normalmente. A auto-hospedagem evita terceiros solicitação e mantém o site utilizável off-line depois que seus ativos são armazenados em cache.

Layouts da direita para a esquerda

Defina direction: rtl para um documento da direita para a esquerda. O tema coloca dir="rtl" no elemento HTML raiz e espelha seu cabeçalho, barra lateral, navegação móvel, paginação, rodapé, menus e controles com propriedades CSS lógicas. Código e os diagramas permanecem intencionalmente da esquerda para a direita.

theme:
  name: primer
  direction: rtl

A direção é uma configuração que abrange todo o site; o tema não o infere de uma página ou localidade do idioma.

Âncoras de direção

Para obter a âncora flutuante do GitHub ao lado de cada título, habilite a extensão toc com um link permanente principal que carrega a classe anchor do Primer:

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

O tema desenha o próprio octicon, então permalink é definido como uma string vazia em vez do que o true habitual. Isso importa mais do que a aparência: o plugin de pesquisa do MkDocs não remova os glifos do link permanente, para que um ¶ apareça nos resultados da pesquisa.

Sem esta configuração, o link permanente ainda funciona, apenas é renderizado como um glifo simples, em vez do que o octicon.

Destaque de sintaxe

As cores do código vêm das variáveis prettylights do Primer, portanto seguem o ativo modo de cor automaticamente. Nenhum estilo Pigmentos precisa ser selecionado:

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences

Os wrappers .highlight e .codehilite são estilizados, portanto codehilite também funciona.

O tema adiciona um botão de cópia a cada bloco Pygments .highlight. Ele copia o fonte visível e anuncia se a operação da área de transferência foi bem-sucedida. Blocos renderizados por plugins, como Mermaid e Vega-Lite, são excluídos intencionalmente.

Controles de navegação

Depois de rolar 400 pixels, um botão voltar ao topo aparece no canto inferior direito da página. Ele retorna o visitante ao início do documento e move foco do teclado no link do título do site. O movimento é instantâneo quando o visitante solicitou movimento reduzido.

Extensões de redução

Nada disso é obrigatório, mas o tema traz um estilo que só compensa uma vez eles estão ligados:

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

admonition é quem vale a pena destacar: a extensão emite marcação e nenhum CSS por si só, e @primer/css também não tem regras para isso, então um estilo sem estilo a advertência é uma surpresa comum. O tema preenche essa lacuna — veja os exemplos.

CSS e JavaScript personalizados

extra_css é carregado após cada folha de estilo enviada pelo tema, então suas regras vencem sem precisar 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 descreve o que colocar nela: as variáveis de layout do próprio tema e por que substituir um token de cor do Primer em :root é descartado, enquanto a mesma regra sob dois seletores de atributo se aplica.

extra_javascript é emitido no final de <body>, após o próprio tema roteiros.

Editar links

O rodapé é vinculado ao arquivo de origem quando repo_url e edit_uri são definidos:

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