Reorganize clients directory and migrate doc processing to MkDocs hooks

Author: joshuadavidthomas

.just/docs.just

@@ -13,20 +13,15 @@ fmt:
 
 # Build documentation
 [no-cd]
-build LOCATION="site": process
+build LOCATION="site":
     uv run --group docs --frozen mkdocs build --config-file {{ mkdoc_config }} --site-dir {{ LOCATION }}
 
 # Serve documentation locally
 [no-cd]
-serve PORT="8000": process
+serve PORT="8000":
     #!/usr/bin/env sh
     HOST="localhost"
     if [ -f "/.dockerenv" ]; then
         HOST="0.0.0.0"
     fi
     uv run --group docs --frozen mkdocs serve --config-file {{ mkdoc_config }} --dev-addr localhost:{{ PORT }}
-
-[no-cd]
-[private]
-process:
-    uv run docs/processor.py

.mkdocs.yml

@@ -1,6 +1,8 @@
 # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
 extra_css:
   - stylesheets/extra.css
+hooks:
+  - docs/hooks.py
 markdown_extensions:
   - attr_list
   - admonition
@@ -18,8 +20,11 @@ markdown_extensions:
   - pymdownx.superfences
   - pymdownx.tasklist:
       custom_checkbox: true
+  - pymdownx.tilde
 plugins:
   - search
+  - include-markdown:
+      rewrite_relative_urls: false
 repo_name: django-language-server
 repo_url: https://github.com/joshuadavidthomas/django-language-server
 site_author: joshuadavidthomas

README.md

@@ -22,7 +22,7 @@ cog.outl(f"![Django Version](https://img.shields.io/badge/django-{'%20%7C%20'.jo
 A language server for the Django web framework.
 
 > [!CAUTION]
-> This project is in early stages. ~All~ Most features are incomplete and missing.
+> This project is in early stages. ~~All~~ Most features are incomplete and missing.
 
 ## Features
 
@@ -105,7 +105,7 @@ The package provides pre-built wheels with the Rust-based LSP server compiled fo
 
 The Django Language Server works with any editor that supports the Language Server Protocol (LSP). We currently have setup instructions for:
 
-- [Neovim](docs/editors/neovim.md)
+- [Neovim](clients/nvim/README.md)
 
 Got it working in your editor? [Help us add setup instructions!](#testing-and-documenting-editor-setup)
 
@@ -141,15 +141,15 @@ The server has only been tested with Neovim. Documentation for setting up the la
 
 If you run into issues setting up the language server:
 
-1. Check the existing documentation in `docs/editors/`
+1. Check the existing documentation in `docs/clients/`
 2. [Open an issue](../../issues/new) describing your setup and the problems you're encountering
    - Include your editor and any relevant configuration
    - Share any error messages or unexpected behavior
    - The more details, the better!
 
 If you get it working in your editor:
 
-1. Create a new Markdown file in the `docs/editors/` directory (e.g., `docs/editors/vscode.md`)
+1. Create a new Markdown file in the `docs/clients/` directory (e.g., `docs/clients/vscode.md`)
 2. Include step-by-step setup instructions, any required configuration snippets, and tips for troubleshooting
 
 Your feedback and contributions will help make the setup process smoother for everyone! 🙌

editors/nvim/README.md renamed to clients/nvim/README.md

@@ -26,7 +26,7 @@ The plugin takes advantage of lazy.nvim's spec loading by providing a `lazy.lua`
     "neovim/nvim-lspconfig",
   },
   config = function(plugin, opts)
-    vim.opt.rtp:append(plugin.dir .. "/editors/nvim")
+    vim.opt.rtp:append(plugin.dir .. "/clients/nvim")
     require("djls").setup(opts)
   end,
 }

editors/nvim/lua/djls/init.lua renamed to clients/nvim/lua/djls/init.lua

@@ -0,0 +1,5 @@
+---
+title: Neovim
+---
+
+{% include-markdown "../../clients/nvim/README.md" %}

docs/clients/neovim.md

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import re
+
+
+def on_page_markdown(markdown, page, config, files):
+    markdown = _convert_admonitions(markdown)
+    markdown = _convert_image_paths(markdown)
+    markdown = _convert_repo_links(markdown, config.repo_url)
+    return markdown
+
+
+def _convert_admonitions(content):
+    ADMONITION_MAP = {
+        "NOTE": "note",
+        "TIP": "tip",
+        "IMPORTANT": "important",
+        "WARNING": "warning",
+        "CAUTION": "warning",
+        "ALERT": "danger",
+        "DANGER": "danger",
+        "INFO": "info",
+        "TODO": "todo",
+        "HINT": "tip",
+    }
+
+    def process_match(match):
+        admonition_type = ADMONITION_MAP.get(match.group(1).upper(), "note")
+        content_lines = match.group(2).rstrip().split("\n")
+        cleaned_lines = [line.lstrip("> ") for line in content_lines]
+        indented_content = "\n".join(
+            f"    {line}" if line.strip() else "" for line in cleaned_lines
+        )
+        trailing_newlines = len(match.group(2)) - len(match.group(2).rstrip("\n"))
+        return f"!!! {admonition_type}\n\n{indented_content}" + "\n" * trailing_newlines
+
+    pattern = r"(?m)^>\s*\[!(.*?)\]\s*\n((?:>.*(?:\n|$))+)"
+    return re.sub(pattern, process_match, content)
+
+
+def _convert_repo_links(content, repo_url):
+    def replace_link(match):
+        text, path = match.group(1), match.group(2)
+
+        if path.startswith(("#", "http://", "https://", "./assets/", "assets/")):
+            return match.group(0)
+
+        if "clients/nvim/README.md" in path:
+            return f"[{text}](clients/neovim.md)"
+
+        clean_path = path.replace("../", "").replace("./", "").lstrip("/")
+        return f"[{text}]({repo_url.rstrip('/')}/blob/main/{clean_path})"
+
+    pattern = r"(?<!!)\[((?:[^][]|\[[^]]*\])*)\]\(([^)]+)\)"
+    return re.sub(pattern, replace_link, content)
+
+
+def _convert_image_paths(content):
+    return re.sub(r"!\[([^\]]*)\]\(\.\/docs\/assets\/", r"![\1](./assets/", content)