Skip to content

Last Updated: 2026-05-04 Owner: Docs-Dev Summary: Reusable prompt for setting up, validating, and extending the QuantMatrix MkDocs documentation site.

QuantMatrix MkDocs Build Prompt

Use this prompt when you want an AI assistant to set up, validate, and document a full MkDocs-based documentation site for the QuantMatrix project.

It is designed to capture both: - the MkDocs build setup itself - the implementation steps already completed in this workspace

Prompt

You are a documentation platform engineer helping me turn an existing Markdown documentation set into a polished MkDocs site using Material for MkDocs.

The project is called QuantMatrix.

I already have a `documentation/docs/` directory with many Markdown documents, plus a legacy custom local HTML documentation portal in `documentation/portal/`. I want MkDocs to become the next-generation documentation platform, while keeping the Markdown files as the source of truth.

Your job is to:
1. set up MkDocs + Material for MkDocs
2. preserve the existing Markdown documents
3. create a strong documentation navigation structure
4. add documentation-maintenance documents
5. scaffold GitHub Pages publishing
6. verify the site builds locally
7. clearly record what was done

Please complete the work in the exact structure below.

## 1. Goals

Build a searchable documentation site for QuantMatrix with:
- left navigation
- top search
- clean section grouping
- a landing page
- contributor workflow
- documentation style guide
- changelog
- GitHub Pages deployment scaffold

Keep the docs modular and easy to maintain.

## 2. Existing Constraints

- The `documentation/docs/` folder is the source of truth
- Existing Markdown files must remain intact unless an update is clearly needed
- A legacy custom documentation portal already exists and should remain usable during transition
- The resulting setup should support local preview first, hosted publishing second

## 3. Required Deliverables

Create or update the following:

- `documentation/mkdocs.yml`
- `documentation/requirements-docs.txt`
- `documentation/docs/index.md`
- `documentation/docs/documentation_contributor_workflow.md`
- `documentation/docs/documentation_style_guide.md`
- `documentation/docs/documentation_changelog.md`
- `documentation/portal/`
- `documentation/tools/`
- `.github/workflows/docs-site.yml`
- `.github/pull_request_template.md`

Also update:
- `README.md`
- `documentation/docs/master_index.md`
- `documentation/docs/todo_next_steps.md`

If there is an existing local portal generator, update it so the new documentation-maintenance docs appear there too.

## 4. Navigation Requirements

The MkDocs site should include sections like:
- Home
- Start Here
- Core Design
- Build and Delivery
- Operations and Runtime
- Incident and Recovery
- Trading Review and Learning
- Data and Contracts
- Contributing

Use the existing documentation set to populate the navigation.

## 5. Theme Requirements

Use Material for MkDocs with:
- search enabled
- navigation sections
- expanded navigation
- light/dark palette
- code copy support
- clean readable defaults

## 6. Verification Requirements

After setup:
- install dependencies in a local virtual environment if needed
- run a strict MkDocs build
- fix any obvious issues found during build
- start a local MkDocs server on a non-conflicting port
- report the local URL

## 7. Documentation Requirements

In the final output, clearly summarize:
- what files were created
- what files were updated
- what remains to fully complete the migration
- what the best next step is

Also preserve the distinction between:
- current implementation state
- target-state documentation strategy

## 8. Steps Already Completed In This Workspace

Assume the following work may already exist and should be reused or verified instead of recreated blindly:

- `documentation/mkdocs.yml`
- `documentation/requirements-docs.txt`
- `documentation/docs/index.md`
- `documentation/docs/documentation_contributor_workflow.md`
- `documentation/docs/documentation_style_guide.md`
- `documentation/docs/documentation_changelog.md`
- `documentation/portal/`
- `documentation/tools/`
- `.github/workflows/docs-site.yml`
- `.github/pull_request_template.md`
- `README.md` documentation-site section
- updates to `documentation/docs/master_index.md`
- updates to `documentation/docs/todo_next_steps.md`
- updates to the legacy custom portal generator so the new docs show there
- a local virtual environment such as `.venv-docs`
- a successful strict MkDocs build
- a local MkDocs server running on a port like `8011`

If these already exist:
- verify them
- improve them if needed
- do not duplicate them unnecessarily

## 9. Quality Bar

Do not leave the setup half-finished.

The result should feel like a real documentation platform foundation, not a minimal placeholder.

Prefer:
- clean navigation
- explicit contributor guidance
- durable docs workflow
- practical local-first setup

At the end, provide:
- local docs URL
- files created
- files updated
- remaining tasks
- recommended next step

What Was Already Done

The following steps were completed in this workspace as part of the first MkDocs rollout:

  1. Added MkDocs site config in documentation/mkdocs.yml
  2. Added docs dependency file documentation/requirements-docs.txt
  3. Added docs landing page documentation/docs/index.md
  4. Added:
  5. documentation/docs/documentation_contributor_workflow.md
  6. documentation/docs/documentation_style_guide.md
  7. documentation/docs/documentation_changelog.md
  8. Added GitHub Pages workflow scaffold in .github/workflows/docs-site.yml
  9. Added pull request template .github/pull_request_template.md
  10. Updated:
  11. README.md
  12. documentation/docs/master_index.md
  13. documentation/docs/todo_next_steps.md
  14. Updated the legacy local docs portal to include the new docs-maintenance pages
  15. Installed MkDocs + Material into a local virtual environment .venv-docs
  16. Ran a successful strict build:
  17. mkdocs build -f documentation/mkdocs.yml --strict
  18. Started a local MkDocs server on:
  19. http://127.0.0.1:8011/quantmatrix/

After this prompt, the next best documentation task is:

  • add last-updated metadata and tagging conventions across the docs
  • then prepare GitHub repository publishing for GitHub Pages