This repository maintains the user documentation for darktable. The content is authored in Markdown and rendered to HTML using Hugo as well as to PDF and EPUB.
The docs currently only track the development version. Versioned docs were last maintained for version 5.2.
The official release documentation is hosted at docs.darktable.org. The auto-built development preview is at darktable-org.github.io/dtdocs.
Please see https://darktable-org.github.io/dtdocs/en/contributing for information about contributing content and how dtdocs are maintained.
For a list of outstanding work please see the issues in this repository and a list of undocumented pull requests in the darktable repository.
Translations are maintained through Weblate.
From a terminal:
git clone https://github.com/darktable-org/dtdocs.git
If cloning the repo fresh, remember to build the bootstrap assets locally:
cd ./themes/hugo-darktable-docs-theme/assets/
yarn install
cd ../../hugo-darktable-docs-pdf-theme/assets/
yarn install
Instead of yarn install you can use npm install.
From the project root:
git pull
And finally make sure the stylesheets are up to date by rebuilding them (see Generating stylesheets).
This site is built with the static site generator Hugo (extended).
You can use a prebuilt binary of the latest extended version for your system. A detailed guide for installation of the prebuilt binaries is given in the Hugo installation documentation.
Building the site to test locally can be done from the root of the repo.
hugo server -D --disableFastRender
This builds the pages locally to the public directory and makes the site available at http://localhost:1313/usermanual/development/ (you can see the URL in the output of the hugo server command).
Note that unless international .md files have been generated with generate-translations.sh --no-update only the english sites will be available.
Run hugo to generate the HTML output files.
hugo
The static files are now available to deploy to a webhost in the public directory. For docs.darktable.org this is automated, see Deployment below.
PDFs can be built with:
./tools/build-pdf.sh
The script generates PDFs by deploying the .html files with hugo server using the config-pdf.yaml and then rendered to PDF with weasyprint. They are written to the public directory. International PDFs will only properly be built if internationalized .md files have been generated with generate-translations.sh --no-update beforehand.
The EPUB can be built with:
./tools/build-epub.sh
This builds an EPUB for every enabled language and writes them to
public/<lang>/darktable_user_manual.epub. As with the PDF, a language is only built if its translated content has been generated first.
See development & deployment within the docs for more detailed information on how dtdocs is deployed.