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 from its docs build path, store/phpbbmodders_documentation/ 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/phpbbmodders_documentation/ 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/phpbbmodders_documentation

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

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

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/phpbbmodders_documentation

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/phpbbmodders_documentation/

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 using ext/phpbbmodders/documentation/docs-build/ if a build was already there. Move it to store/phpbbmodders_documentation/ and update the docs build path, because updating the extension replaces its directory and deletes the build.

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/phpbbmodders_documentation

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

The build writes a Pagefind search index for each language and top-level section, at <lang>/<section>/pagefind/.

Full-text search runs in the visitor's browser and needs JavaScript. The Documentation extension only gives the browser the indexes for sections the current user may read.

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.