Ir para o conteúdo principal
Version: 2.0.0-beta.9

Temas

Como plugins, os temas são projetados para adicionar funcionalidades ao seu site Docusaurus. Como regra geral, os temas são mais focados no lado do cliente, onde os plug-ins são mais focados nas funcionalidades do lado do servidor. Os temas também são projetados para serem substituídos por outros temas.

Temas disponíveis

Mantemos uma lista de temas oficiais.

Usando temas

Para usar temas, especifique os temas no seu docusaurus.config.js. Você pode usar vários temas:

docusaurus.config.js
module.exports = {
// ...
themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};

Componentes do tema

Na maioria das vezes, o tema é usado para fornecer um conjunto de componentes React, por exemplo, Navbar, Layout, Footer.

Os usuários podem usar esses componentes em seu código importando-os usando o alias do webpack @theme:

import Navbar from '@theme/Navbar';

O alias @theme pode se referir a alguns diretórios, na seguinte prioridade:

  1. Diretório website/src/theme de um usuário, é um diretório especial que tem maior precedência.
  2. Um diretório theme de pacotes de temas do Docusaurus.
  3. Componentes substitutos fornecidos pelo núcleo do Docusaurus (geralmente não são necessários).

Dada a seguinte estrutura

website
├── node_modules
│ └── docusaurus-theme
│ └── theme
│ └── Navbar.js
└── src
└── theme
└── Navbar.js

website/src/theme/Navbar.js tem prioridade sempre que @theme/Navbar for importado. Este comportamento é denominado swizzling de componentes. No iOS, swizzling de método é o processo de alterar a implementação de um seletor (método) existente. No contexto de um site, o componentes swizzling significa fornecer um componente alternativo que tem precedência sobre o componente fornecido pelo tema.

Temas são para fornecer componentes UI para apresentar o conteúdo. A maioria dos plugins de conteúdo precisam ser emparelhados com um tema para serem realmente úteis. The UI is a separate layer from the data schema, so it makes it easy to swap out the themes for other designs.

Por exemplo, um blog Docusaurus consiste em um plugin de blog e um tema do blog.

docusaurus.config.js
{
theme: ['theme-blog'],
plugins: ['plugin-content-blog'],
}

E se você quiser usar o estilo Bootstrap, você pode trocar o tema com theme-blog-bootstrap (fictício não existente tema):

docusaurus.config.js
{
theme: ['theme-blog-bootstrap'],
plugins: ['plugin-content-blog'],
}

Empacotando seu site com <Root>

Um componente temático <Root> é renderizado no topo do seu site Docusaurus.

Ele permite que você encapsule seu site com lógica adicional, criando um arquivo em src/theme/Root.js:

website/src/theme/Root.js
import React from 'react';

// Default implementation, that you can customize
function Root({children}) {
return <>{children}</>;
}

export default Root;

Este componente é aplicado acima do roteador e do tema <Layout> e nunca desmontará.

tip

Use este componente para renderizar provedores React Context e lógica global stateful.

Componentes do tema Swizzling

caution

Nós desencorajamos o swizzling de componentes durante a fase beta do Docusaurus 2. É provável que as APIs dos componentes do tema evoluam e tenham alterações significativas. Se possível, mantenha a aparência padrão por enquanto.

Os componentes dos Temas Docusaurus são projetados para serem substituíveis. Para tornar mais fácil, nós criamos um comando para você substituir os componentes do tema chamados swizzle.

Para swizzle um componente para um tema, execute o seguinte comando no seu site do documento:

npm run swizzle <theme name> [component name]

Como exemplo, para desfazer o componente <Footer /> em @docusaurus/theme-classic para o seu site, execute:

npm run swizzle @docusaurus/theme-classic Footer

Isto irá copiar o atual componente <Footer /> usado pelo tema para o diretório src/theme/Footer na raiz do seu site, que é onde o Docusaurus procurará por componentes enfeitados. O Docusaurus usará o componente deslizante no lugar do original do tema.

Embora desencorajemos fortemente o swizzling de todos os componentes, se você deseja fazer isso, execute:

npm run swizzle @docusaurus/theme-classic

Note: Você precisa reiniciar seu servidor de desenvolvimento de webpack para que o Docusaurus saiba sobre o novo componente.

Empacotando componentes do tema

Às vezes, você só quer encapsular um componente de tema existente com lógica adicional, e pode ser uma dor ter que manter uma cópia quase duplicada do componente de tema original.

Neste caso, você deve deslizar o componente que você deseja encapsular, mas importe o componente de tema original na sua versão personalizada para encapsulá-lo.

Para proprietários de sites

O alias @theme-original permite que você importe o componente original do tema.

Aqui está um exemplo para exibir algum texto logo acima do rodapé, com duplicação mínima de código.

src/theme/Footer.js
// Note: importing from "@theme/Footer" would fail due to the file importing itself
import OriginalFooter from '@theme-original/Footer';
import React from 'react';

export default function Footer(props) {
return (
<>
<div>Before footer</div>
<OriginalFooter {...props} />
</>
);
}

Para autores de plugins

Um tema pode encapsular um componente de outro tema, importando o componente do tema inicial, usando a importação de @theme-init.

Aqui está um exemplo de como usar este recurso para aprimorar o componente padrão do tema CodeBlock com um recurso de playground react-live.

import InitialCodeBlock from '@theme-init/CodeBlock';
import React from 'react';

export default function CodeBlock(props) {
return props.live ? (
<ReactLivePlayground {...props} />
) : (
<InitialCodeBlock {...props} />
);
}

Verifique o código do docusaurus-theme-live-codeblock para detalhes.

caution

A menos que você queira publicar no npm um "aprimorador de tema" (como docusaurus-theme-live-codeblock), você provavelmente não precisa de @theme-init.

Design de temas

Enquanto os temas compartilham exatamente os mesmos métodos de ciclo de vida com plugins, suas implementações podem parecer muito diferentes das de plugins baseados nos objetivos projetados dos temas.

Os temas são projetados para completar a compilação do seu site Docusaurus e fornecer os componentes usados pelo seu site, plugins e os próprios temas. Então um modelo típico de implementação de tema se parece com um arquivo src/index.js que conecta ele aos métodos do ciclo de vida. Muito provavelmente eles não usariam o loadContent, quais plugins usariam. E normalmente é acompanhado por um diretório src/theme cheio de componentes.

Para resumir:

  • Temas compartilham os mesmos métodos de ciclo de vida com Plugins
  • Os temas são executados após todos os plugins existentes
  • Existem temas para adicionar aliases de componente estendendo o webpack config

Escrevendo temas personalizados do Docusaurus

Um tema Docusaurus normalmente inclui um arquivo index.js onde você se conecta aos métodos de ciclo de vida, junto com um diretório theme/ de componentes. Uma pasta theme típica de Docusaurus tem esta aparência:

website
├── package.json
└── src
├── index.js
└── theme
├── MyThemeComponent
└── AnotherThemeComponent.js

Existem dois métodos do ciclo de vida que são essenciais para a implementação do tema:

Estes métodos de ciclo de vida não são essenciais, mas recomendados: