phpbbdocs hugo Website Setup

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 stored in its docs-build/ directory.

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 Documentation extension.

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 its own docs-build/ directory by default.

From the phpbbdocs-hugo repository, run:

./phpbbdocs_hugo.sh all /path/to/phpbb/ext/phpbbmodders/documentation/docs-build

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

./phpbbdocs_hugo.sh all /var/www/phpbb/ext/phpbbmodders/documentation/docs-build

all builds every available language.

A single language can also be built:

./phpbbdocs_hugo.sh fr /var/www/phpbb/ext/phpbbmodders/documentation/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.
5. Writes the completed static site to docs-build/.

Enable the Documentation extension

Enable the extension from:

ACP → Customise → Manage extensions

When the Hugo output is written directly to:

ext/phpbbmodders/documentation/docs-build/

the extension's default docs build path can be used without further configuration.

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 docs-build

The raw 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 docs-build/ could bypass those permission checks.

Apache and LiteSpeed

The extension includes an .htaccess file that blocks direct access to docs-build/.

This works with Apache when AllowOverride is enabled for the directory and with LiteSpeed/OpenLiteSpeed's Apache-compatible .htaccess handling.

Other web servers

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/ext/phpbbmodders/documentation/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 docs-build/.

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

Search

The Hugo build generates a search-index.json for each language.

The Documentation extension uses these indexes for full-text documentation searches while applying the current user's language and section permissions.

Rebuild the Hugo site after documentation changes so the search indexes remain synchronized 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.