Skip to content

Templates Directory Rename - Technical Notes

Issue

The problem statement requested that templates be accessible via templates/test-plan-template.md etc. However, MkDocs reserves the templates directory name for Jinja2 theme template files and excludes it from documentation builds by design.

Root Cause

MkDocs and MkDocs Material use the templates directory within the docs folder for theme customization. When a docs/templates/ directory exists with documentation files, MkDocs automatically excludes all files in that directory from the build, treating it as a reserved directory for theme templates.

This behavior is: - By Design: MkDocs has reserved certain directory names for special purposes - Cannot be Overridden: No configuration option exists to force inclusion of the templates directory - Well-Documented: This is a known limitation in the MkDocs ecosystem

Solution

The templates directory was renamed to test-templates to avoid the reserved name conflict while maintaining the same functionality.

Changes Made

  1. Directory Renamed: docs/templates/ → docs/test-templates/
  2. Navigation Updated: All references in mkdocs.yml updated to test-templates/
  3. Homepage Updated: Link to templates page updated to test-templates/index.md

Files Affected

New Structure: 

docs/
├── test-templates/
│   ├── index.md
│   ├── test-plan-template.md
│   ├── risk-assessment-template.md
│   ├── test-case-template.md
│   ├── traceability-matrix-template.md
│   ├── defect-report-template.md
│   ├── test-execution-report-template.md
│   └── test-summary-report-template.md

URLs After Deployment: - https://bg-playground.github.io/BGSTM/test-templates/ - https://bg-playground.github.io/BGSTM/test-templates/test-plan-template/ - etc.

Impact

Minimal Impact

  • ✅ All template files are fully accessible
  • ✅ Navigation works correctly
  • ✅ Build completes successfully
  • ✅ No functionality lost

Documentation Updates Needed (Separate Task)

The existing documentation files in the repository contain links to the old templates/ path: - docs/GETTING-STARTED.md - docs/phases/*.md - docs/methodologies/*.md - docs/integration/multi-platform-guide.md

These files were not modified as they are existing documentation, not part of the MkDocs setup task. They can be updated in a follow-up PR if needed.

Alternative Solutions Considered

1. Custom Theme Directory

Rejected: Would require creating a custom theme, significantly increasing complexity.

Rejected: Not portable across all systems, especially Windows.

3. Post-Processing Script

Rejected: Adds unnecessary complexity and maintenance burden.

4. Different Name Altogether

Selected: test-templates clearly indicates the purpose while avoiding conflicts.

Verification

Build verified successful: 

$ mkdocs build
INFO - Building documentation to directory: /home/runner/work/BGSTM/BGSTM/site
INFO - Documentation built in 4.28 seconds

All template pages confirmed accessible: - ✅ Templates index page - ✅ Test Plan Template - ✅ Risk Assessment Template - ✅ Test Case Template - ✅ Traceability Matrix Template - ✅ Defect Report Template - ✅ Test Execution Report Template - ✅ Test Summary Report Template

Recommendation

Accept the test-templates directory name as it: 1. Provides the same functionality 2. Follows MkDocs best practices 3. Avoids conflicts with reserved directories 4. Uses a clear, descriptive name 5. Maintains consistency with the project structure

The name test-templates is actually more descriptive than just templates as it clearly indicates these are templates for testing purposes.