Managing Multiple Documentations Sharing the Same Files using Hooks #3904

Smaacky · 2025-01-16T19:08:23Z

Smaacky
Jan 16, 2025

Hello all, I am trying to figure out how to manage two sites of documentation that share the same purpose but for different audiences: production and development into one branch.

Thank you for your help in advance! Any help is appreciated.

Problem

I am trying to use hooks to change the in-text links to refer to different sources. For prod files, I want them to refer to other prod sources.

I have been able to use the on_page_markdown Reference event to modify default generated URL for prod and dev sites

page.file.name = page.file.name.replace("_prod","")
page.file.url = page.file.url.replace("_prod","")
page.file.dest_uri = page.file.dest_uri.replace("_prod","")
page.file.abs_dest_path = page.file.abs_dest_path.replace("_prod","")

prod_site.com/procedure_prod is now prod_site.com/procedure.

My problem is the hooks are not changing the in-text links appropriately to prod_site.com/procedure instead of prod_site.com/procedure_prod. When I click on a link in the page, the link takes me to the latter and not the former so I get a 404 error since the latter does not exist.

The in-text link on the markdown files is [link](procedure_prod.md#section_1) after running the above hook. I even tried replacing the raw markdown content directly when the event was called.

markdown = markdown.replace("_prod","") --> this didnt change the resulting html since I checked via on_page_content Reference event the resultant generated html was procedure_prod.html instead of procedure.html which is what I wanted.

Context

I have two versions of documentation that I want to publish for the production and development teams maintained on the same branch.

Both sets of documentation share the same purpose and general content. The differences lie in the following

Different operational procedures for the same problems
Removing extra information from dev, not needed in prod.

They also share a lot of the same information

images
common procedures

This is the current structure

mkdocs workspace
│   config_dev.yml
│   config_prod.yml    
│
└───docs
   │   procedure_dev.md
   │   procedure_prod.md
   |   common_procedure.md
   │
   └───Common Folder Name
   │   procedure_dev.md
   │   procedure_prod.md

kokoc30 · 2026-11-05T23:50:36Z

kokoc30
Nov 5, 2026

Move the output-path mapping to on_files, before navigation and Markdown links are built. Keep the source URI unchanged: a link such as procedure_prod.md#section_1 should still identify the existing source file, whose output URL can be procedure/.

For the physical files in your example, this is one explicit mapping for a MkDocs 1.6.1 production build:

# hooks_prod.py
from mkdocs.structure.files import File

OUTPUTS = {
    'procedure_prod.md': 'procedure/index.html',
    'Common Folder Name/procedure_prod.md':
        'Common Folder Name/procedure/index.html',
}


def on_files(files, config):
    for old in list(files):
        destination = OUTPUTS.get(old.src_uri)
        if destination is None:
            continue
        replacement = File(
            old.src_uri,
            old.src_dir,
            old.dest_dir,
            old.use_directory_urls,
            dest_uri=destination,
            inclusion=old.inclusion,
        )
        files.remove(old)
        files.append(replacement)
    return files

In the production config:

use_directory_urls: true
hooks:
  - hooks_prod.py

Leave Markdown links and nav entries pointing to the original *_prod.md source names. MkDocs resolves those source names to the mapped file and generates the destination link, retaining the fragment. That lookup is visible in the relative-link processor.

Using a new File here also avoids inconsistent cached attributes: url and abs_dest_path are derived from dest_uri and cached. Mutating several of them independently in on_page_markdown is fragile. The 1.6.1 File implementation supports the explicit dest_uri constructor argument.

Use a corresponding development mapping in the development config, and exclude the other audience's variant from each build so two sources cannot target the same output. Shared files can retain their normal names. This changes the URL mapping without globally replacing _prod inside prose, code examples, or unrelated paths.

The files event is intended for this stage of file manipulation. If you also edit Markdown in a page hook, remember to return the modified string; assigning a local markdown variable alone does not replace the event's result. I checked this against the linked source, rather than executing your site build.

0 replies

Navigation Menu

Repository navigation

Managing Multiple Documentations Sharing the Same Files using Hooks #3904

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Managing Multiple Documentations Sharing the Same Files using Hooks #3904

Uh oh!

Smaacky Jan 16, 2025

Problem

Context

Replies: 1 comment

Uh oh!

kokoc30 Nov 5, 2026

Smaacky
Jan 16, 2025

kokoc30
Nov 5, 2026