Chapter 4. Documentation Directory Structure

Files and directories in the doc/ tree follow a structure meant to:

  1. Make it easy to automate converting the document to other formats.

  2. Promote consistency between the different documentation organizations, to make it easier to switch between working on different documents.

  3. Make it easy to decide where in the tree new documentation should be placed.

In addition, the documentation tree must accommodate documents in many different languages. It is important that the documentation tree structure does not enforce any particular defaults or cultural preferences.

4.1. The Top Level, doc/

There are three sections under doc/, documentation and website share the same structure.

DirectoryUsage

documentation

Contains all the articles and books in AsciiDoc format. Contains subdirectories to further categorize the information by languages.

shared

Contains files that are not specific to the various translations of the documentation. Contains subdirectories to further categorize the information by languages and three files to store the authors, releases and mirrors information. This directory is shared between documentation and the website.

website

Contains the FreeBSD website in AsciiDoc format. Contains subdirectories to further categorize the information by languages.

4.2. The Directories

These directories contain the documentation and the website. The documentation is organized into subdirectories below this level, following the Hugo directory structure.

DirectoryUsage

archetypes

Contain templates to create new articles, books and webpages. For more information take a look here.

config

Contain the Hugo configuration files. One main file and one file per language. For more information take a look here.

content

Contain the books, articles and webpages. One directory exists for each available translation of the documentation, for example en and zh-tw.

data

Contain custom data for build the website in TOML format. This directory is used to store the events, news, press, etc. For more information take a look here.

static

Contain static assets. Images, security advisories, the pgpkeys, etc. For more information take a look here.

themes

Contain the templates in the form of .html files that specify how the website looks. For more information take a look here.

tools

Contain tools used to enhance the documentation build. For example to generate the Table of Contents of the books, etc.

beastie.png

This image doesn’t need an introduction ;)

LICENSE

License of the documentation, shared and website. BSD 2-Clause License.

Makefile

The Makefile defines the build process of the documentation and the website.

4.3. Document-Specific Information

This section contains specific notes about particular documents managed by the FDP.

4.4. The Books: books/

The books are written in AsciiDoc.

The books are organized as an AsciiDoc book. The books are divided into parts, each of which contains several chapters. chapters are further subdivided into sections (=) and subsections (==, ===) and so on.

4.4.1. Physical Organization

There are a number of files and directories within the books directory, all with the same structure.

4.4.1.1. _index.adoc

The _index.adoc defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables and the abstract section.

4.4.1.2. book.adoc

The _index.adoc defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables, the abstract section and all the chapters. This file is used to generate the PDF with asciidoctor-pdf and to generate the book in one html page.

4.4.1.3. part*.adoc

The part*.adoc files stores a brief introduction of one part of the book.

4.4.1.4. toc*.adoc

The toc*.adoc files stores the Table of Contents, Table of Figures, Table of Examples, Table of Tables and different Table of Contents for each part. All of these files are generated by the Python tools. Please don’t edit them.

4.4.1.5. chapters-order.adoc

The chapters-order.adoc file stores the order of the book chapters.

Please be careful with this file. It is used by the Python tools to generate the Table of Contents of the books. In case of editing this file, first contact the Documentation Engineering team.

4.4.1.6. directory/_index.adoc

Each chapter in the Handbook is stored in a file called _index.adoc in a separate directory from the other chapters.

For example, this is an example of the header of one chapter:

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

[[kernelconfig]]
\= Configuring the FreeBSD Kernel (1)
...
1The character at the end of the line should not be used in a production document. This character is here to skip this title in the autogenerated toc-*.adoc files.

When the HTML5 version of the Handbook is produced, this will yield kernelconfig/index.html.

A brief look will show that there are many directories with individual _index.adoc files, including basics/_index.adoc, introduction/_index.adoc, and printing/_index.xml.

Do not name chapters or directories after their ordering within the Handbook. This ordering can change as the content within the Handbook is reorganized. Reorganization should be possible without renaming files, unless entire chapters are being promoted or demoted within the hierarchy.

4.5. The Articles: articles/

The articles are written in AsciiDoc.

The articles are organized as an AsciiDoc article. The articles are divided into sections (=) and subsections (==, ===) and so on.

4.5.1. Physical Organization

There is one _index.adoc file per article.

4.5.1.1. _index.adoc

The _index.adoc file contains all the AsciiDoc variables and the content.

For example, this is an example of one article, the structure is pretty similar to one book chapter:

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

\= Why you should use a BSD style license for your Open Source Project (1)
:doctype: article
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:source-highlighter: rouge
:experimental:

'''

toc::[]

[[intro]]
\== Introduction (1)
1The character at the end of the line should not be used in a production document. This character is here to skip this title in the autogenerated toc-*.adoc files.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.