Repository navigation
Markdown Page Functionality - #68
Merged
Merged
Conversation
- dynamically constructs menu from folder structure of html and md root folders - retains HTML rendering as before - Still WIP but is pretty darn close
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds first-class support for browsing and rendering markdown-based documentation alongside the existing generated HTML docs, wiring both into the Blazor UI (home page + nav) and container deployment.
Changes:
- Introduces
DocsService(Markdig-powered) and a new/docs/{*DocPath}page to render markdown content from a configured filesystem root. - Introduces
HtmlDocsServiceplus reusable section link components to replace hardcoded HTML doc link lists and provide a generic/html/{SectionSlug}/{Filename?}browsing experience. - Updates app configuration and container mounts to supply both
apsim-docs-htmlandapsim-docs-mdcontent at runtime.
Reviewed changes
Copilot reviewed 24 out of 25 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| Services/HtmlDocsService.cs | Adds section/page discovery and HTML rendering for generated docs. |
| Services/DocsService.cs | Adds markdown tree indexing, front-matter/title parsing, and markdown-to-HTML rendering. |
| Program.cs | Registers the new docs services in DI. |
| docker-compose.yml | Mounts the markdown docs folder into the container. |
| Components/Pages/Validation.razor | Switches validation HTML rendering to use HtmlDocsService + section links. |
| Components/Pages/Tutorials.razor | Uses the new HTML section links component for tutorials. |
| Components/Pages/Tutorial.razor | Switches tutorial HTML rendering to HtmlDocsService. |
| Components/Pages/TechnicalInfo.razor | Adds a new page which links into a markdown section. |
| Components/Pages/Models.razor | Switches models HTML rendering to HtmlDocsService. |
| Components/Pages/Model.razor | Uses the new HTML section links component for models. |
| Components/Pages/HtmlDocs.razor | Adds a generic HTML section/page browser route. |
| Components/Pages/Home.razor | Lists both HTML sections and markdown top-level sections on the home page. |
| Components/Pages/Docs.razor | Adds the main markdown docs browsing/rendering route. |
| Components/Layout/NavMenu.razor | Builds nav items dynamically from available HTML/markdown sections. |
| Components/Layout/ValidationLinks.razor | Replaces hardcoded validation link cards with section link component usage. |
| Components/Layout/TutLinks.razor | Replaces hardcoded tutorial link cards with section link component usage. |
| Components/Layout/ModelLinks.razor | Replaces hardcoded model link cards with section link component usage. |
| Components/Layout/HtmlSectionLinks.razor | New component for listing HTML pages in a section. |
| Components/Layout/DocSectionLinks.razor | New component for listing markdown pages/directories in a section. |
| Components/Custom/DocLink.razor | Updates namespace to APSIM.Docs.Components.Custom. |
| APSIM.Docs.csproj | Adds Markdig package reference. |
| appsettings.json | Adds Docs options (roots for markdown + HTML). |
| appsettings.Development.json | Adds Docs options (roots for markdown + HTML). |
| .gitignore | Ignores the mounted docs directories. |
| .dockerignore | Excludes mounted docs directories from Docker build context. |
| remove-later.txt | Removes a temporary build trigger file. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
par456
approved these changes
Jul 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
resolves #67
Allows the displaying of markdown files along side the current html formatted docs.