Skip to content

phpbbdocs hugo Website Setup

Jump to bottom
William Jacoby edited this page Oct 7, 2026 · 4 revisions

phpbbdocs-hugo Website Setup

This guide explains how to use phpbbdocs-hugo with the Documentation phpBB extension.

phpbbdocs-hugo builds the phpBB user and developer documentation as a static Hugo site. The Documentation extension serves that generated site through phpBB at /documentation, using the active board style and phpBB permissions.

The projects have separate responsibilities:

  • phpbbdocs-hugo handles documentation sources, translations, Hugo templates, and building the static site.
  • Documentation integrates the generated site into phpBB and serves the files from its docs build path, store/docs_build/ by default.

Requirements

Install the Documentation extension normally at:

ext/phpbbmodders/documentation/

The system used to build phpbbdocs-hugo needs at least:

  • Git
  • Hugo
  • xsltproc
  • rsync

Additional tools are required when maintaining translations. See the phpbbdocs-hugo documentation for the translation workflow.

Clone phpbbdocs-hugo

phpbbdocs-hugo does not need to be located inside the phpBB installation. It only needs to be able to write the finished build to the docs build path.

git clone https://github.com/phpbbmodders/phpbbdocs-hugo.git
cd phpbbdocs-hugo

Update the upstream documentation

Before producing a fresh website build, update the English documentation from the official phpBB documentation repository:

./pull_upstream_docs.sh

This synchronizes the local English documentation source with phpbb/documentation.

If translations or developer documentation are being maintained, complete the appropriate update and translation workflow before producing the final site build.

Build the website

The Documentation extension expects the generated Hugo site in phpBB's store/docs_build/ directory by default. Keeping it outside the extension's own directory means updating the extension doesn't delete it.

From the phpbbdocs-hugo repository, run:

./phpbbdocs_hugo.sh all /path/to/phpbb/store/docs_build

For example, if phpBB is installed at /var/www/phpbb:

./phpbbdocs_hugo.sh all /var/www/phpbb/store/docs_build

The directory is created by the first build; enabling the extension doesn't create it.

all builds every available language.

A single language can also be built:

./phpbbdocs_hugo.sh fr /var/www/phpbb/store/docs_build

For the live website, a full all build is normally preferred so all available languages are regenerated together.

The build script:

  1. Finds the available proteus_doc_<language>.xml sources.
  2. Generates Hugo Markdown for each requested language.
  3. Copies the corresponding documentation images.
  4. Runs Hugo, writing the completed static site to the given directory.
  5. Builds the Pagefind search indexes for each language and section.

Enable the Documentation extension

Enable the extension from:

ACP → Customise → Manage extensions

When the Hugo output is written directly to:

store/docs_build/

the extension's default docs build path can be used without further configuration. A build kept elsewhere can be set in the extension's settings under Docs build path.

Boards upgraded from an earlier version keep an earlier default, ext/phpbbmodders/documentation/docs-build/ or store/phpbbmodders_documentation/, if a build was already there. A build inside the extension's directory should be moved to store/docs_build/ and the docs build path updated, because updating the extension replaces its directory and deletes the build; the settings page warns about this. If a build is moved without updating the setting, the extension reads it from store/docs_build/ and the settings page asks for the setting to be updated.

The documentation is then available through phpBB at:

/documentation

Languages

The Documentation extension can automatically select documentation based on the user's phpBB language. Users can also select a language manually.

phpBB and Hugo language codes do not always match. For example, phpBB may use a code such as pt_br while the documentation build uses pt-BR.

The extension handles matching and broad-language fallbacks automatically. Additional mappings can be configured with Language code overrides in the extension settings when necessary.

Permissions

Documentation is available to everyone, including guests, by default.

Access can be restricted through phpBB's normal permission system. Permissions can be assigned by documentation section and language.

When a new language or top-level documentation section is added to the Hugo build, go to the Documentation extension settings and use:

Resync permissions

This creates the corresponding phpBB permission entries for the new content.

Protect the docs build

The docs build directory must not be directly accessible from the web.

Visitors should access documentation through phpBB's /documentation routes. This allows the Documentation extension to apply its language and section permissions.

Allowing direct HTTP access to the build could bypass those permission checks.

The default location

phpBB already blocks web access to store/: through its store/.htaccess on Apache (with AllowOverride enabled) and LiteSpeed/OpenLiteSpeed, and through the store rule in phpBB's sample Nginx and lighttpd configs and its IIS web.config. Check that your server config includes that rule if it wasn't built from phpBB's samples.

Caddy and other locations

phpBB ships no Caddy sample, and a build kept anywhere else needs its own rule. The extension includes example deny rules for:

  • Nginx
  • Caddy
  • IIS
  • lighttpd

See Securing the docs build directory for the appropriate configuration.

These snippets should be merged into the existing site configuration rather than used as complete replacement configurations.

Updating the website

For a normal documentation refresh:

cd /path/to/phpbbdocs-hugo

git pull --ff-only
./pull_upstream_docs.sh
./phpbbdocs_hugo.sh all /path/to/phpbb/store/docs_build

If translations or developer documentation have changed, update or rebuild those sources before running the final phpbbdocs_hugo.sh command.

The Documentation extension does not need to be reinstalled or re-enabled after a documentation rebuild. It reads the newly generated files directly from the docs build path.

If the rebuild introduces a new language or top-level section, use Resync permissions in the ACP afterward.

Search

For each language and top-level section, the build writes a Pagefind search index at <lang>/<section>/pagefind/ and a server-side index at <lang>/<section>/search-index.json.

With JavaScript, search runs in the visitor's browser with Pagefind, and the Documentation extension only gives the browser the indexes for sections the current user may read. Without JavaScript, or when a build has no Pagefind indexes, the extension searches the server-side indexes of those same sections instead.

The number of results shown is set by Search results limit in the extension settings (10-200, default 50).

Rebuild the Hugo site after documentation changes so the search indexes stay in step with the generated pages.

The sidebar Filter is separate from full-text search and filters navigation titles only.

phpbbdocs-hugo documentation

More detailed information about maintaining and building the documentation is available in the phpbbdocs-hugo Wiki, including:

  • Build & Publish Workflow
  • Script Reference
  • Translator Workflow

Those guides cover maintaining the documentation sources and translations. This page specifically covers deploying the finished phpbbdocs-hugo site through the phpBB Documentation extension.

Clone this wiki locally