Markdown Page Functionality

.dockerignore

@@ -0,0 +1,2 @@
+apsim-docs-html
+apsim-docs-md

.gitignore

@@ -134,3 +134,5 @@ _NCrunch*
 
 # Specific ignores
 *.html
+apsim-docs-md
+apsim-docs-html

APSIM.Docs.csproj

@@ -2,6 +2,7 @@
 
   <ItemGroup>
     <PackageReference Include="Blazor.Bootstrap" Version="3.2.0" />
+    <PackageReference Include="Markdig" Version="1.3.2" />
   </ItemGroup>
 
   <PropertyGroup>

Components/Custom/DocLink.razor

@@ -6,7 +6,7 @@
 @inject NavigationManager NavigationManager
 
 
-@namespace Components.Custom
+@namespace APSIM.Docs.Components.Custom
 
 <div class="col-xl-3 col-lg-3 col-md-6 col-sm-12 g-2 d-flex">
     <div class="card card-hover-shadow w-100">

Components/Layout/DocSectionLinks.razor

@@ -0,0 +1,75 @@
+@using APSIM.Docs.Components.Custom
+@using APSIM.Docs.Services
+@inject IDocsService DocsService
+
+@namespace APSIM.Docs.Components.Layout
+
+@if (entries.Count == 0)
+{
+    <p>No documentation entries were found in this section.</p>
+}
+else
+{
+    <div class="container">
+        <div class="row">
+            @foreach (var entry in entries)
+            {
+                <DocLink
+                    DocDisplayName="@entry.Title"
+                    DocModelName="@entry.Title"
+                    DocDescript="@entry.Description"
+                    DocLinkHref="@entry.Href" />
+            }
+        </div>
+    </div>
+}
+
+@code {
+    private readonly List<SectionLinkEntry> entries = [];
+
+    [Parameter]
+    public string? SectionSlug { get; set; }
+
+    [Parameter]
+    public bool IncludeIndexPage { get; set; }
+
+    protected override void OnParametersSet()
+    {
+        entries.Clear();
+
+        var sectionNode = string.IsNullOrWhiteSpace(SectionSlug)
+            ? DocsService.GetTree()
+            : DocsService.TryGetDirectory(SectionSlug);
+
+        if (sectionNode is null)
+        {
+            return;
+        }
+
+        if (IncludeIndexPage && sectionNode.IndexPage is not null)
+        {
+            entries.Add(new SectionLinkEntry(
+                sectionNode.IndexPage.Title,
+                "Overview for this section.",
+                $"/docs/{sectionNode.IndexPage.SlugPath}"));
+        }
+
+        foreach (var childDirectory in sectionNode.Directories.OrderBy(directory => directory.Name, StringComparer.OrdinalIgnoreCase))
+        {
+            entries.Add(new SectionLinkEntry(
+                childDirectory.Name,
+                "Click to see more",
+                $"/docs/{childDirectory.SlugPath}"));
+        }
+
+        foreach (var page in sectionNode.Pages.OrderBy(page => page.Title, StringComparer.OrdinalIgnoreCase))
+        {
+            entries.Add(new SectionLinkEntry(
+                page.Title,
+                page.Summary ?? "Open documentation page.",
+                $"/docs/{page.SlugPath}"));
+        }
+    }
+
+    private sealed record SectionLinkEntry(string Title, string Description, string Href);
+}

Components/Layout/HtmlSectionLinks.razor

@@ -0,0 +1,50 @@
+@using APSIM.Docs.Components.Custom
+@using APSIM.Docs.Services
+@inject IHtmlDocsService HtmlDocsService
+
+@namespace APSIM.Docs.Components.Layout
+
+@if (section is null)
+{
+    <p>No documentation entries were found in this section.</p>
+}
+else
+{
+    <div class="container">
+        <div class="row">
+            @foreach (var htmlPage in section.Pages)
+            {
+                <DocLink
+                    DocDisplayName="@htmlPage.DisplayName"
+                    DocModelName="@htmlPage.DisplayName"
+                    DocDescript="Open HTML documentation page."
+                    DocLinkHref="@BuildHref(htmlPage)" />
+            }
+        </div>
+    </div>
+}
+
+@code {
+    private HtmlDocSection? section;
+
+    [Parameter]
+    public string? SectionSlug { get; set; }
+
+    [Parameter]
+    public string? LinkBaseHref { get; set; }
+
+    protected override void OnParametersSet()
+    {
+        section = HtmlDocsService.TryGetSection(SectionSlug);
+    }
+
+    private string BuildHref(HtmlDocPage page)
+    {
+        if (!string.IsNullOrWhiteSpace(LinkBaseHref))
+        {
+            return $"{LinkBaseHref!.TrimEnd('/')}/{page.FileStem}";
+        }
+
+        return $"/html/{page.SectionSlug}/{page.FileStem}";
+    }
+}

Components/Layout/ModelLinks.razor

@@ -1,24 +1,7 @@
-@using Components.Custom
-@namespace Components.Layout
+@using APSIM.Docs.Components.Layout
 
-<div class="container">
+@namespace APSIM.Docs.Components.Layout
 
-    <div id="row-1" class="row">
-        <DocLink DocModelName="Clock" 
-            DocDisplayName="Clock"
-            DocDescript="Model documentation for Clock." 
-            DocLinkHref="model/Clock"/>
-
-        <DocLink DocModelName="ZadokPMFWheat" 
-            DocDisplayName="ZadokPMFWheat" 
-            DocDescript="Model documentation for ZadokPMFWheat." 
-            DocLinkHref="model/ZadokPMFWheat"/>
-
-        <DocLink DocModelName="Waterlogging"
-            DocDisplayName="Waterlogging" 
-            DocDescript="Model documentation for Waterlogging model." 
-            DocLinkHref="model/Waterlogging"/>
-    </div>
-</div>
+<DocSectionLinks SectionSlug="model-documentation" IncludeIndexPage="true" />
 
 

Components/Layout/NavMenu.razor

@@ -1,4 +1,8 @@
-<div class="top-row ps-3 mb-5 navbar navbar-dark">
+@using APSIM.Docs.Services
+@inject IHtmlDocsService HtmlDocsService
+@inject IDocsService DocsService
+
+<div class="top-row ps-3 mb-5 navbar navbar-dark">
     <div class="container-fluid">      
         <a class="navbar-brand" href="/">
             <img src="APSIM_transparent-154x100.png" />
@@ -10,31 +14,54 @@
 
 <div class="nav-scrollable" onclick="document.querySelector('.navbar-toggler').click()">
     <nav class="flex-column">
-        <div class="nav-item px-3">
-            <NavLink class="nav-link" href="" Match="NavLinkMatch.All">
-                <span class="" aria-hidden="true">
-                    <Icon Name="IconName.ClipboardCheckFill" Size="IconSize.x2" class="me-3 ms-1"></Icon>
-                </span> Validation
-            </NavLink>
-        </div>
-
-        <div class="nav-item px-3">
-            <NavLink class="nav-link" href="tutorials">
-                <span class="" aria-hidden="true">
-                    <Icon Name="IconName.BookFill" Size="IconSize.x2"class="me-3 ms-1"></Icon>
-                </span> Tutorials
-            </NavLink>
-        </div>
-
-        <div class="nav-item px-3">
-            <NavLink class="nav-link" href="models">
-                <span class="" aria-hidden="true">
-                    <Icon Name="IconName.FileCodeFill" Size="IconSize.x2" class="me-3 ms-1"></Icon>
-                </span> Models
-            </NavLink>
-        </div>
+        <div class="nav-item px-3 text-white-50 small mt-2">APSIM Generated Docs</div>
+        @foreach (var item in HtmlMenuItems)
+        {
+            <div class="nav-item px-3">
+                <NavLink class="nav-link" href="@item.Href" Match="NavLinkMatch.Prefix">
+                    <span class="" aria-hidden="true">
+                        <Icon Name="@item.IconName" Size="IconSize.x2" class="me-3 ms-1"></Icon>
+                    </span> @item.Title
+                </NavLink>
+            </div>
+        }
+
+        <div class="nav-item px-3 text-white-50 small mt-3">APSIM User Docs</div>
+        @foreach (var item in MarkdownMenuItems)
+        {
+            <div class="nav-item px-3">
+                <NavLink class="nav-link" href="@item.Href" Match="NavLinkMatch.Prefix">
+                    <span class="" aria-hidden="true">
+                        <Icon Name="@item.IconName" Size="IconSize.x2" class="me-3 ms-1"></Icon>
+                    </span> @item.Title
+                </NavLink>
+            </div>
+        }
     </nav>
 </div>
 
+@code {
+    private IEnumerable<NavMenuItem> HtmlMenuItems => HtmlDocsService
+        .GetSections()
+        .Select(section => new NavMenuItem(section.Name, GetHtmlSectionHref(section.Slug), IconName.FileCodeFill));
+
+    private IEnumerable<NavMenuItem> MarkdownMenuItems => DocsService
+        .GetTopLevelSections()
+        .Select(section => new NavMenuItem(section.Name, $"/docs/{section.SlugPath}", IconName.JournalText));
+
+    private static string GetHtmlSectionHref(string sectionSlug)
+    {
+        return sectionSlug switch
+        {
+            "models" => "/models",
+            "tutorials" => "/tutorials",
+            "validation" => "/validation",
+            _ => $"/html/{sectionSlug}"
+        };
+    }
+
+    private sealed record NavMenuItem(string Title, string Href, IconName IconName);
+}
+
 
 

Components/Layout/TutLinks.razor

@@ -1,84 +1,3 @@
-@using Components.Custom
 @namespace Components.Layout
 
-<div class="container">
-    <div class="row">
-        <DocLink DocModelName="ClimateController" 
-            DocDisplayName="Climate Controller"
-            DocLinkHref="tutorial/ClimateController"
-            DocDescript="Usage of climate control manager component.">
-        </DocLink> 
-
-        <DocLink DocModelName="Lifecycle" 
-            DocDisplayName="Lifecycle"
-            DocLinkHref="tutorial/Lifecycle"
-            DocDescript="Describes managing the lifecycle of a pseudoaphid.">
-        </DocLink> 
-
-        <DocLink DocModelName="Manager" 
-            DocDisplayName="Manager"
-            DocLinkHref="tutorial/Manager"
-            DocDescript="Provides two tutorials covering sowing fertiliser topup and water and N topup rules.">
-        </DocLink> 
-
-        <DocLink DocModelName="Sensitivity_MorrisMethod"
-            DocDisplayName="Parameter sensitivity (Morris)"
-            DocLinkHref="tutorial/Sensitivity_MorrisMethod"
-            DocDescript="Describes the process of using the Morris method for parameter sensitivity analysis.">
-        </DocLink> 
-
-        <DocLink DocModelName="Sensitivity_SobolMethod"
-            DocDisplayName="Parameter sensitivity (SOBOL)"
-            DocLinkHref="tutorial/Sensitivity_SobolMethod"
-            DocDescript="Describes the process of using the SOBOL method for parameter sensitivity analysis.">
-        </DocLink> 
-
-        <DocLink DocModelName="Sensitivity_FactorialANOVA"
-            DocDisplayName="Parameter sensitivity (Factorial ANOVA)" 
-            DocLinkHref="tutorial/Sensitivity_FactorialANOVA"
-            DocDescript="Describes the process of using the Factorial ANOVA method for parameter sensitivity analysis.">
-        </DocLink> 
-
-        <DocLink DocModelName="PredictedObserved"
-            DocDisplayName="Predicted/Observed Data Handling"
-            DocLinkHref="tutorial/PredictedObserved"
-            DocDescript="Describes the process of predicted/observed data handling for fitting plant models.">
-        </DocLink> 
-
-        <DocLink DocModelName="Report" 
-            DocDisplayName="Report"
-            DocLinkHref="tutorial/Report"
-            DocDescript="Provides tutorials and instruction on how to use the Report model.">
-        </DocLink> 
-
-        <DocLink DocModelName="CLEM Documentation site" 
-            DocDisplayName="CLEM Documentation site"
-            DocLinkHref="https://www.apsim.info/clem/Content/Home.htm"
-            DocDescript="Specific site for CLEM information">
-        </DocLink> 
-
-        <DocLink DocModelName="CLEM_Example_Cropping" 
-            DocDisplayName="CLEM Cropping Examples"
-            DocLinkHref="tutorial/CLEM_Example_Cropping"
-            DocDescript="Setting up cropping simulations">
-        </DocLink> 
-
-        <DocLink DocModelName="CLEM_Example_Grazing" 
-            DocDisplayName="CLEM Grazing Example"
-            DocLinkHref="tutorial/CLEM_Example_Grazing"
-            DocDescript="CLEM grazing simulation example">
-        </DocLink> 
-
-        <DocLink DocModelName="TreadingDamageInPastures" 
-            DocDisplayName="Treading Damage in Pastures"
-            DocLinkHref="tutorial/TreadingDamageInPastures"
-            DocDescript="Enabling Livestock Treading Effects on Soil and Pastures">
-        </DocLink> 
-
-        <DocLink DocModelName="InitialisingSoilCarbonPools" 
-            DocDisplayName="Initialising Soil Carbon Pools"
-            DocLinkHref="tutorial/InitialisingSoilCarbonPools"
-            DocDescript="Instructions for initialising soil carbon pools">
-        </DocLink> 
-    </div>
-</div>
+<APSIM.Docs.Components.Layout.DocSectionLinks SectionSlug="user-tutorials" IncludeIndexPage="true" />