Capítulo 4. Estrutura de Diretórios da Documentação | FreeBSD Documentation Portal
Description: Explicação da Estrutura de Diretórios usada no Projeto de Documentação do FreeBSD
Keywords: directory structure,organization

# Capítulo 4. Estrutura de Diretórios da Documentação

Esta tradução pode estar desatualizada. Para ajudar com as traduções, acesse a ferramenta de traduções do FreeBSD.

Arquivos e diretórios no repositório doc/ seguem uma estrutura destinada a:

1. Facilitar a conversão do documento para outros formatos.

2. Promover a consistência entre as diferentes organizações de documentação, e assim facilitar a alternância entre diferentes documentos.

3. Facilitar a decisão de onde a nova documentação deve ser colocada.

Além disso, o repositório de documentação deve acomodar documentos em vários idiomas e codificações diferentes. É importante que a estrutura do repositório de documentação não imponha quaisquer padrões particulares ou preferências culturais.

## 4.1. O Nível Superior, doc/

Existem dois tipos de diretório em doc/, documentation e website, ambos compartilham a mesma estrutura.

Diretório | Uso
--- | ---
documentation | Contém todos os artigos e livros em formato AsciiDoc. Contém subdiretórios para categorizar ainda mais as informações por idiomas.
tools | Contém um conjunto de ferramentas usadas para traduzir a documentação e o site usando Weblate. A instância do Weblate pode ser acessada aqui.
shared | Contém arquivos que não são específicos para as várias traduções da documentação. Contém subdiretórios para categorizar ainda mais as informações por idiomas e três arquivos para armazenar as informações dos autores, lançamentos e espelhos. Este diretório é compartilhado entre `documentation` e o `website`.
website | Contém o site do FreeBSD no formato AsciiDoc Contém subdiretórios para categorizar ainda mais as informações por idiomas.

## 4.2. Os Diretórios

Esses diretórios contêm a documentação e o website. A documentação está organizada em subdiretórios abaixo deste nível, seguindo o estrutura de diretórios Hugo.

Diretório | Uso
--- | ---
archetypes | Contém templates para criar novos artigos, livros e páginas web. Para mais informações, veja aqui.
config | Contém os arquivos de configuração do Hugo. Um arquivo principal e um arquivo por idioma. Para mais informações, veja aqui.
content | Contém os livros, artigos e páginas web. Existe um diretório para cada tradução disponível da documentação, por exemplo `en` e `zh-tw`.
data | Contem dados personalizados para compilar o site no formato TOML. Este diretório é usado para armazenar os eventos, notícias, imprensa, etc. Para mais informações, veja aqui.
static | Contem ativos estáticos. Imagens, avisos de segurança, pgpkeys, etc. Para mais informações, veja aqui.
themes | Contém os modelos na forma de arquivos `.html` que especificam a aparência do site. Para mais informações, veja aqui.
tools | Contém ferramentas usadas para aprimorar a construção da documentação. Por exemplo, para gerar o índice dos livros, etc.
beastie.png | Esta imagem não precisa de introdução ;)
LICENSE | Licença da documentação e site. Licença BSD de 2 cláusulas.
Makefile | O Makefile que executa o processo de compilação da documentação e do website.

## 4.3. Informação Específica de Documentação

Esta seção contém informações específicas sobre documentos gerenciados pelo FDP.

## 4.4. Os Livros: books/

Os livros são escritos em AsciiDoc.

Para cada livro do FreeBSD, o tipo de documento AsciiDoc (também conhecido como doctype) é `book`. Os livros possuem `part`es, cada uma contendo vários `capítulos` (chapter).

Quando o documento é convertido para HTML 5 (usando o backend `html5` embutido):

- A seção AsciiDoc nível 0 (`=`) no início de um `capítulo` de um `livro` será `<h1>`

- A seção AsciiDoc nível 1 (`==`) deve ser usada para a primeira seção lógica de um capítulo e será `<h2>`

- A seção AsciiDoc nível 2 (`===`) deve ser usada para a primeira subseção lógica e será `<h3>`

– e assim por diante. Referência: Títulos e Níveis de Seção | Asciidoctor Docs.

### 4.4.1. Organização Física

Existem vários arquivos e diretórios no diretório books, todos com a mesma estrutura.

#### 4.4.1.1. _index.adoc

O arquivo _index.adoc define algumas variáveis AsciiDoc que afetam como o código AsciiDoc é convertido para outros formatos e lista o Índice, a Tabela de Exemplos, a Tabela de Figuras, a Tabela de Tabelas e a seção de resumo.

#### 4.4.1.2. book.adoc

O arquivo book.adoc define algumas variáveis AsciiDoc que afetam como o código AsciiDoc é convertido para outros formatos e lista o Índice, a Tabela de Exemplos, a Tabela de Figuras, a Tabela de Tabelas, a seção de resumo e todos os capítulos. Este arquivo é usado para gerar o PDF com `asciidoctor-pdf` e para gerar o livro em uma página `html`.

#### 4.4.1.3. part*.adoc

Os arquivos part*.adoc armazenam uma breve introdução de uma parte do livro.

#### 4.4.1.4. directory/_index.adoc

Cada capítulo do Handbook é armazenado em um arquivo chamado _index.adoc em um diretório separado dos outros capítulos.

Por exemplo, este é um exemplo do cabeçalho de um capítulo:

    ---
    title: Chapter 8. Configuring the FreeBSD Kernel
    part: Part II. Common Tasks
    prev: books/handbook/multimedia
    next: books/handbook/printing
    ---

    [[kernelconfig]]
    = Configurando o kernel do FreeBSD
    ...

Quando a versão HTML5 do Handbook é produzida, será gerado o kernelconfig/index.html.

Uma breve olhada mostrará que existem muitos diretórios com arquivos _index.adoc individuais, incluindo basics/_index.adoc, introduction/_index.adoc, e printing/_index.xml.

| Não nomeie capítulos ou diretórios com a ordenação do Handbook. Essa ordenação pode mudar conforme o conteúdo do Handbook é reorganizado. A reorganização deve ser realizada sem renomear arquivos, a menos que capítulos inteiros sejam promovidos ou rebaixados dentro da hierarquia.

## 4.5. Os Artigos: articles/

Os artigos são escritos em AsciiDoc.

Os artigos são organizados como um `artigo` do AsciiDoc. Os artigos são divididos em seções (`=`) e subseções (`==`, `===`) e assim por diante.

### 4.5.1. Organização Física

Existe um arquivo _index.adoc por artigo.

#### 4.5.1.1. _index.adoc

O arquivo _index.adoc contém todas as variáveis AsciiDoc e o conteúdo.

Por exemplo, este é um exemplo de um artigo, a estrutura é muito semelhante a um capítulo de livro:

    ---
    title: Why you should use a BSD style license for your Open Source Project
    authors:
      - author: Bruce Montague
        email: brucem@alumni.cse.ucsc.edu
    trademarks: ["freebsd", "intel", "general"]
    ---

    = Por que você deve usar uma licença de estilo BSD em seu Projeto Open Source
    :doctype: article
    :toc: macro
    :toclevels: 1
    :icons: font
    :sectnums:
    :source-highlighter: rouge
    :experimental:

    '''

    toc::[]

    [[intro]]
    == Introdução

Última alteração em: 18 de junho de 2026 por Alexander Ziaee

Anterior
Início
Próximo