Add custom template parameter (#61)

Author: sindrehan

CHANGELOG.md

@@ -5,6 +5,9 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2025-11-19
+- Add support for passing custom Jinja2 templates as an argument, by @sindrehan.
+
 ## [1.2.1] - 2025-07-30
 
 - Added support for using the current working directory (CWD) as an option when

README.md

@@ -73,6 +73,34 @@ oad gen-docs -s source-openapi.json -d schemas.wsd --style "PLANTUML_API"
 
 _Example of PlantUML diagram generated from path items._
 
+#### Using custom templates
+
+You can override the default templates by providing a custom templates directory:
+
+```bash
+oad gen-docs -s source-openapi.json -d output.md -T ./my-templates/
+```
+
+The custom templates directory should contain template files with the same names as the built-in templates. Any template file found in the custom directory will override the corresponding default template, while non-overridden templates will use the defaults. This follows the same pattern as [MkDocs template customization](https://www.mkdocs.org/user-guide/customizing-your-theme/#overriding-template-blocks).
+
+**Important:** The custom templates directory must match the output style being rendered. Each style (MKDOCS, MARKDOWN, PLANTUML_SCHEMAS, PLANTUML_API) has its own template structure. You need to provide templates appropriate for the `--style` parameter you're using.
+
+**Template structure:**
+- `layout.html` - Main layout template
+- `partial/` - Directory containing reusable template components
+
+**Example custom template directory structure:**
+```
+my-templates/
+├── layout.html          # Overrides main layout
+└── partial/
+    ├── info.html       # Overrides info section
+    └── path-items.html # Overrides path items section
+```
+
+All templates use [Jinja2](https://jinja.palletsprojects.com/) syntax and have access to the same filters, functions, and context variables as the built-in templates.
+
+
 ### Goals
 
 * Provide an API to generate OpenAPI Documentation files.

openapidocs/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "1.2.1"
+__version__ = "1.3.0"
 VERSION = __version__

openapidocs/commands/docs.py

@@ -31,7 +31,20 @@
     default="MKDOCS",
     show_default=True,
 )
-def generate_documents_command(source: str, destination: str, style: Union[int, str]):
+@click.option(
+    "-T",
+    "--templates",
+    help=(
+        "Path to a custom templates directory. "
+        "Templates in this directory will override default templates with matching names. "
+        "Unspecified templates will use defaults."
+    ),
+    required=False,
+    default=None,
+)
+def generate_documents_command(
+    source: str, destination: str, style: Union[int, str], templates: Union[str, None]
+):
     """
     Generates other kinds of documents from source OpenAPI Documentation files.
 
@@ -48,7 +61,7 @@ def generate_documents_command(source: str, destination: str, style: Union[int,
     https://github.com/Neoteroi/essentials-openapi
     """
     try:
-        generate_document(source, destination, style)
+        generate_document(source, destination, style, templates)
     except KeyboardInterrupt:  # pragma: nocover
         logger.info("User interrupted")
         exit(1)

openapidocs/mk/generate.py

@@ -1,13 +1,22 @@
+from typing import Optional
+
 from openapidocs.mk.v3 import OpenAPIV3DocumentationHandler
 from openapidocs.utils.source import read_from_source
 
 
-def generate_document(source: str, destination: str, style: int | str):
+def generate_document(
+    source: str,
+    destination: str,
+    style: int | str,
+    templates_path: Optional[str] = None,
+):
     # Note: if support for more kinds of OAD versions will be added, handle a version
     # parameter in this function
 
     data = read_from_source(source)
-    handler = OpenAPIV3DocumentationHandler(data, style=style, source=source)
+    handler = OpenAPIV3DocumentationHandler(
+        data, style=style, source=source, templates_path=templates_path
+    )
 
     html = handler.write()
 

openapidocs/mk/jinja.py

@@ -1,10 +1,20 @@
 """
 This module provides a Jinja2 environment.
 """
+
 import os
 from enum import Enum
-
-from jinja2 import Environment, PackageLoader, Template, select_autoescape
+from pathlib import Path
+from typing import Optional
+
+from jinja2 import (
+    ChoiceLoader,
+    Environment,
+    FileSystemLoader,
+    PackageLoader,
+    Template,
+    select_autoescape,
+)
 
 from . import get_http_status_phrase, highlight_params, read_dict, sort_dict
 from .common import DocumentsWriter, is_reference
@@ -62,29 +72,50 @@ def __init__(
 
 
 def get_environment(
-    package_name: str, views_style: OutputStyle = OutputStyle.MKDOCS
+    package_name: str,
+    views_style: OutputStyle = OutputStyle.MKDOCS,
+    custom_templates_path: Optional[str] = None,
 ) -> Environment:
     templates_folder = f"views_{views_style.name}".lower()
 
+    loaders = []
+
+    # If custom templates path is provided, validate and add FileSystemLoader first
+    if custom_templates_path:
+        custom_path = Path(custom_templates_path)
+        if not custom_path.exists():
+            raise ValueError(
+                f"Custom templates path does not exist: {custom_templates_path}"
+            )
+        if not custom_path.is_dir():
+            raise ValueError(
+                f"Custom templates path is not a directory: {custom_templates_path}"
+            )
+        loaders.append(FileSystemLoader(str(custom_path)))
+
+    # Always add the package loader as fallback
     try:
-        loader = PackageLoader(package_name, templates_folder)
+        loaders.append(PackageLoader(package_name, templates_folder))
     except ValueError as package_loading_error:  # pragma: no cover
-        raise PackageLoadingError(
-            views_style, templates_folder
-        ) from package_loading_error
-    else:
-        env = Environment(
-            loader=loader,
-            autoescape=select_autoescape(["html", "xml"])
-            if os.environ.get("SELECT_AUTOESCAPE") in {"YES", "Y", "1"}
-            else False,
-            auto_reload=True,
-            enable_async=False,
-        )
-        configure_filters(env)
-        configure_functions(env)
+        if not custom_templates_path:
+            raise PackageLoadingError(
+                views_style, templates_folder
+            ) from package_loading_error
+
+    loader = ChoiceLoader(loaders)
+
+    env = Environment(
+        loader=loader,
+        autoescape=select_autoescape(["html", "xml"])
+        if os.environ.get("SELECT_AUTOESCAPE") in {"YES", "Y", "1"}
+        else False,
+        auto_reload=True,
+        enable_async=False,
+    )
+    configure_filters(env)
+    configure_functions(env)
 
-        return env
+    return env
 
 
 class Jinja2DocumentsWriter(DocumentsWriter):
@@ -97,8 +128,9 @@ def __init__(
         self,
         package_name: str,
         views_style: OutputStyle = OutputStyle.MKDOCS,
+        custom_templates_path: Optional[str] = None,
     ) -> None:
-        self._env = get_environment(package_name, views_style)
+        self._env = get_environment(package_name, views_style, custom_templates_path)
 
     @property
     def env(self) -> Environment:

openapidocs/mk/v3/__init__.py

@@ -1,6 +1,7 @@
 """
 This module provides functions to generate Markdown for OpenAPI Version 3.
 """
+
 import copy
 import os
 import warnings
@@ -95,11 +96,14 @@ def __init__(
         writer: Optional[DocumentsWriter] = None,
         style: Union[int, str] = 1,
         source: str = "",
+        templates_path: Optional[str] = None,
     ) -> None:
         self._source = source
         self.texts = texts or EnglishTexts()
         self._writer = writer or Jinja2DocumentsWriter(
-            __name__, views_style=style_from_value(style)
+            __name__,
+            views_style=style_from_value(style),
+            custom_templates_path=templates_path,
         )
         self.doc = self.normalize_data(copy.deepcopy(doc))