Repository: mkdocs/mkdocs

Issue:
Building MkDocs' documentation
When I began working on #3493 I needed to be able to run the dev server with MkDocs' own documentation, which was more difficult than it should have been.

First, let me say that I always work from a venv, and created a new one to start my work. In the past, one could simply do `pip install -r requirements/docs.txt` and then `mkdocs serve` and it worked.  But I had to jump through a lot of hoops and learn new tools to get things working this time.

To be clear, I am not suggesting that the old tools should be brought back. Nor am I suggesting that my preferred tools be used. However, I could find no documentation about how to proceed. Eventually, I did find documentation that hatch is used for tests, and looking at `pyproject.toml` I could see a config for a hatch `docs` env. But not having ever used that tool before, it took be multiple tries (and searches) to work out how to even use that env. But, I'm getting ahead of myself...

After realizing that there were no requirements.txt files, I next looked for optional dependencies defined in `pyproject.toml`. I was hoping to maybe do `pip install .[docs]` (`.` rather than `markdown` because I was working from the working tree of the git repo). When I determined that that wasn't an option, I began looking into the hatch options. Finally in some random question in some forum I found an explanation of how to run the `shell` subcommand with an alternate env: `hatch -e docs shell`.

And then I could finally run `mkdocs serve`. Except that I got an error about missing `po` files, which is weird because I am using English, which should work without any translations being defined. Finally, after generating `po` and `mo` files, I could run the dev server and begin my work.

All of this led me to believe that the current maintainers are not ever running the dev server with MkDocs documentation. And I also could not find any automations for deploying the documentation, so I couldn't even use that as a reference.

Again, I am not being critical of the tool choices. I see that a switch was made from tox to hatch. That's fine if that is the tool that the maintainers what to use. But for an occasional contributor, I would prefer to not need to learn these tools. I would prefer to be able to use standard Python tools that work with any project. Or if I do need to use your tool of choice, then I would expect the specific commands I would need to use to all be documented clearly.

I could submit a PR which updated the documentation, but I'm not sure what the recommended best practices are here. I am simply bringing this to the attention of the maintainers with the hopes that more consideration will be given to this in the future.


Discussion:
Options for running docs:

* `hatch run docs:mkdocs serve` / `build`

* `virtualenv .venv; .venv/bin/pip install $(mkdocs get-deps); .venv/bin/mkdocs serve` / `build`

* With https://github.com/mkdocs/mkdocs/pull/3502
  `virtualenv .venv; .venv/bin/pip install -r requirements/requirements-docs.txt; .venv/bin/mkdocs serve` / `build`

> could not find any automations

Also covered in that PR

Maintainer of Hatch and Hatchling here! Let me know if I can be of assistance 🙂
Thanks. Everything about Hatch is good and clear *to me*, I just didn't document the setup, that's the issue

Resolving patch:
diff --git a/docs/hooks.py b/docs/hooks.py
--- a/docs/hooks.py
+++ b/docs/hooks.py
@@ -1,8 +1,12 @@
+from __future__ import annotations
+
 import re
 from pathlib import Path
+from typing import TYPE_CHECKING
 
-from mkdocs.config.defaults import MkDocsConfig
-from mkdocs.structure.nav import Page
+if TYPE_CHECKING:
+    from mkdocs.config.defaults import MkDocsConfig
+    from mkdocs.structure.nav import Page
 
 
 def _get_language_of_translation_file(path: Path) -> str:
@@ -13,7 +17,7 @@ def _get_language_of_translation_file(path: Path) -> str:
     return m[1]
 
 
-def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, **kwargs):
+def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, **kwargs) -> str | None:
     if page.file.src_uri == 'user-guide/choosing-your-theme.md':
         here = Path(config.config_file_path).parent
 


Test patch: