Add PDF compilation pipeline for Developer Guide

[Copilot]

Plan: Compile Developer Guide to PDF

• Create pandoc title.txt file with YAML metadata block in docs/guide/
• Create pandoc definition.yaml file in docs/guide/ with resource paths, input files, template, TOC, and section numbering
• Create docs/template/ directory
• Create simple HTML template in docs/template/guide_template.html
• Create build_docs.yaml reusable workflow
• Install required tools (mermaid-filter, mermaid, DemaConsulting.PandocTool, DemaConsulting.WeasyprintTool)
• Add pandoc and weasyprint commands to generate PDF
• Verify the workflow is correctly formatted
• Fix YAML linting issues
• Run pre-finalization quality checks
• Address PR feedback:
  • Extract CSS from HTML template to separate guide_template.css file
  • Update workflow to stay in repo root (better docker support)
  • Upload only PDF artifact (not HTML)
• Address code review comments:
  • Fix CSS relative path to work correctly from generated HTML location
  • Simplify YAML command syntax for better reliability
• Fix tool commands and platform:
  • Change runner to windows-latest (WeasyprintTool requires Windows)
  • Fix pandoc command from pandoc-tool to pandoc
  • Fix weasyprint command from weasyprint-tool to weasyprint
• Fix input file path:
  • Change from guide.md to docs/guide/guide.md for explicit path resolution
• Refactor workflow structure:
  • Extract build-docs job to separate build_docs.yaml reusable workflow
  • Call build_docs.yaml from both build_on_push.yaml and release.yaml
  • Prevents duplicate runs when build.yaml is called twice
• Fix naming convention:
  • Rename build-docs.yaml to build_docs.yaml (underscore naming)
• Manage dependencies properly:
  • Add npm dependencies to package.json with pinned versions
  • Add dotnet tools to .config/dotnet-tools.json with pinned versions
  • Update workflow to use npm install and dotnet tool restore
• Simplify package.json:
  • Remove unnecessary name, version, and description fields
  • Keep only private flag and devDependencies
• Use dotnet prefix for tool execution:
  • Change pandoc to dotnet pandoc
  • Change weasyprint to dotnet weasyprint
  • Use multi-line YAML format for clarity

Summary

Successfully implemented PDF compilation for the Developer Guide with all feedback addressed:

Files Created:

1. docs/guide/title.txt - YAML metadata
2. docs/guide/definition.yaml - Pandoc configuration with full paths
3. docs/template/guide_template.html - HTML template with external CSS reference
4. docs/template/guide_template.css - Extracted stylesheet
5. .github/workflows/build_docs.yaml - Reusable workflow for building documentation
6. package.json - Minimal npm configuration with devDependencies only

Files Modified:

• .config/dotnet-tools.json - Added PandocTool@3.8.3 and WeasyprintTool@67.0.0
• .gitignore - Added node_modules/
• build_on_push.yaml - Calls build_docs.yaml after quality checks
• release.yaml - Calls build_docs.yaml during release process
• build.yaml - Removed build-docs job to prevent duplicate execution

Workflow Changes:

• build_docs.yaml - Reusable workflow:
  • Runs on Windows (WeasyprintTool requirement)
  • Uses npm install for npm dependencies
  • Uses dotnet tool restore for dotnet tools
  • Executes pandoc and weasyprint via dotnet (local tools, not global)
  • Uses multi-line YAML format for clarity
  • Stays in repo root (docker-friendly)
  • Uploads only PDF artifact
• build_on_push.yaml - Calls build_docs.yaml after quality checks (runs once)
• release.yaml - Calls build_docs.yaml during release process (runs once)

Dependency Management:

All dependencies are now managed through configuration files with pinned versions:

• npm dependencies: Minimal package.json with only private flag and devDependencies
• dotnet tools: Managed via .config/dotnet-tools.json and executed with dotnet prefix
• Workflow uses npm install and dotnet tool restore for reproducible builds

Quality Checks:

✅ Build: Successful (0 warnings)
✅ Tests: All 27 tests passing
✅ YAML Linting: Compliant
✅ JSON Validation: All JSON files valid
✅ Naming Convention: Consistent with repository standards
✅ Dependency Management: Versions pinned in config files
✅ Tool Execution: Using dotnet prefix for local tools

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature]: Compile Develoiper Guide to PDF</issue_title>
<issue_description>### Problem Statement

The Developer Guide should be available to the user as a PDF.

Proposed Solution

The proposal is to use "pandoc", "mermaid-filter", and "weasyprint" to compile the developer guide to PDF. This would entail:

1. Adding a pandoc title.txt file to the docs/guide folder which consists of a yaml metadata block containing document metadata information such as the title, subtitle, lang, and keywords for the PDF.
2. Adding a pandoc definition.yaml file to the docs/guide folder consisting of a resource-path pointing to both the docs/guide and a new 'docs/template' folder; an input-files specifying the guide.md file, a template set to guide_template.html, table-of-contents set true, and a number-sections set true.
3. Add a simple HTML template in docs/template/guide_template.html
4. A new build-docs job in build.yaml which installs mermaid-filter, mermaid, DemaConsulting.PandocTool and DemaConsulting.WeasyprintTool and then runs pandoc then weasyprint to create the PDF.

Alternatives Considered

No response

Usage Examples

Benefits

Easier access to usage documentation

Priority

Medium - Would improve my workflow

Willingness to Contribute

Yes, I can submit a pull request

Additional Context

No response

Checklist

• I have searched existing issues to ensure this is not a duplicate
• I have provided a clear description of the feature
• I have explained why this feature would be useful</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Feature]: Compile Develoiper Guide to PDF #57

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Malcolmnixon]

Consider making a guide_template.css file and moving some of the style information to that file.

[Copilot]

Consider making a guide_template.css file and moving some of the style information to that file.

Done. Created guide_template.css and updated the HTML template to reference the external stylesheet. (b198d25)

[Malcolmnixon]

rename build-docs.yaml to build_docs.yaml to match the repository naming convention.

[Copilot]

rename build-docs.yaml to build_docs.yaml to match the repository naming convention.

Fixed. Renamed to build_docs.yaml and updated all references in build_on_push.yaml and release.yaml. (b89a8f5)

[Malcolmnixon]

As pandoc isn't being installed globally, it needs to be executed using dotnet. Also for clarity let's use the yaml multi-line format with one option per line - as follows:

      - name: Generate HTML with Pandoc
        run: >
          pandoc
          docs/guide/title.txt
          --defaults docs/guide/definition.yaml
          --output docs/guide/guide.html

[Copilot]

Fixed. Changed to dotnet pandoc and reformatted using multi-line YAML with one option per line. (ff9737d)

[Malcolmnixon]

Again weasyprint isn't being installed globally, so it needs to be executed using dotnet and should use multi-line format:

      - name: Generate PDF with Weasyprint
        run: >
          dotnet weasyprint
          docs/guide/guide.html
          docs/guide/guide.pdf

[Copilot]

Fixed. Changed to dotnet weasyprint and reformatted using multi-line YAML with one argument per line. (ff9737d)