Skip to content

Commit 5a2d992

Browse files
pkbullockpkbullock
authored
Merge pull request #1 from pkbullock/copilot/upgrade-docfx-and-theme
Upgrade DocFx from 2.56.7 to 2.78.4, convert custom JS to vanilla JavaScript
2 parents ffb8993 + 262beaf commit 5a2d992

13 files changed

Lines changed: 515 additions & 252 deletions

File tree

‎.config/dotnet-tools.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"version": 1,
3+
"isRoot": true,
4+
"tools": {
5+
"docfx": {
6+
"version": "2.78.4",
7+
"commands": [
8+
"docfx"
9+
],
10+
"rollForward": false
11+
}
12+
}
13+
}

‎.github/workflows/docfx-generate.yml‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -30,17 +30,15 @@ jobs:
3030
with:
3131
ref: gh-pages
3232
path: gh-pages
33-
# Install docfx, stick with version 2.51 as higher versions result in https://github.com/dotnet/docfx/issues/5785 > fixed in 2.56.4+
34-
- name: Install dependencies
33+
# Install .NET SDK (if not already available) and DocFx as a dotnet tool
34+
- name: Setup .NET
35+
uses: actions/setup-dotnet@v4
36+
with:
37+
dotnet-version: '8.x'
38+
- name: Install DocFx
3539
run: |
36-
wget https://github.com/dotnet/docfx/releases/download/v2.56.7/docfx.zip
37-
sudo unzip docfx.zip -d /usr/local/lib/docfx
38-
rm docfx.zip
39-
echo '#!/bin/sh' | sudo tee -a /usr/local/bin/docfx > /dev/null
40-
echo 'exec `which mono` $MONO_OPTIONS /usr/local/lib/docfx/docfx.exe "$@"' | sudo tee -a /usr/local/bin/docfx > /dev/null
41-
sudo chmod +wx /usr/local/bin/docfx
42-
sudo mkdir /usr/local/lib/docfx/plugins
43-
sudo cp ./main/docfx/plugins/* /usr/local/lib/docfx/plugins
40+
cd main
41+
dotnet tool restore
4442
# Build docs
4543
- name: Build docs
4644
shell: pwsh

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ staging
22
docfx/matrix.md
33
docfx/metadata.md
44
docfx/cmdusage.md
5+
docfx/_site
56

67
# Mac files
78
.DS_Store

‎DOCFX-UPGRADE.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# DocFx Upgrade Guide
2+
3+
## Overview
4+
5+
This repository has been upgraded from **DocFx 2.56.7** to **DocFx 2.78.4**. The upgrade modernizes the documentation build process while maintaining the existing material theme look and feel.
6+
7+
## What Changed
8+
9+
### Build System
10+
- **Before**: DocFx 2.56.7 installed as a standalone executable requiring Mono on Linux/macOS
11+
- **After**: DocFx 2.78.4 installed as a .NET tool, no Mono dependency required
12+
13+
### Benefits
14+
- ✅ Cross-platform compatibility without Mono
15+
- ✅ Easier installation and updates via .NET tooling
16+
- ✅ Better performance and stability
17+
- ✅ Active maintenance and bug fixes
18+
- ✅ Material theme fully preserved
19+
- ✅ All existing features maintained
20+
21+
## Local Development Setup
22+
23+
### Prerequisites
24+
- .NET SDK 6.0 or higher ([Download here](https://dotnet.microsoft.com/download))
25+
26+
### First Time Setup
27+
1. Clone the repository
28+
2. Navigate to the repository root
29+
3. Restore the DocFx tool:
30+
```bash
31+
dotnet tool restore
32+
```
33+
34+
### Building the Documentation
35+
36+
#### Quick Build
37+
From the `docfx` folder:
38+
```bash
39+
dotnet docfx build docfx.json
40+
```
41+
42+
Or use the provided script:
43+
```powershell
44+
./docfx-build-local.ps1
45+
```
46+
47+
#### Build and Serve Locally
48+
To preview the site locally:
49+
```bash
50+
cd docfx
51+
dotnet docfx docfx.json --serve --port 8080
52+
```
53+
54+
Then open your browser to `http://localhost:8080`
55+
56+
### CI/CD Pipeline
57+
58+
The GitHub Actions workflow (`.github/workflows/docfx-generate.yml`) has been updated to:
59+
1. Use `actions/setup-dotnet@v4` to install .NET SDK
60+
2. Run `dotnet tool restore` to install DocFx
61+
3. Execute the build using `dotnet docfx`
62+
63+
No changes needed for manual deployments - the workflow handles everything automatically.
64+
65+
## Theme Information
66+
67+
The site uses a custom material theme based on [Oscar Vasquez's DocFx Material theme](https://ovasquez.github.io/docfx-material/).
68+
69+
### Theme Files
70+
- `docfx/templates/material/` - Custom theme templates
71+
- `layout/_master.tmpl` - Main layout template
72+
- `partials/` - Reusable template components (navbar, footer, head, etc.)
73+
- `styles/` - Custom CSS and JavaScript files
74+
75+
### Color Scheme
76+
The theme uses a cyan color palette defined in `styles/main.css`:
77+
- Header background: `#006064` (dark cyan)
78+
- Highlight light: `#428e92` (teal)
79+
- Highlight dark: `#00363a` (very dark cyan)
80+
81+
## Troubleshooting
82+
83+
### "docfx: command not found"
84+
Make sure you've run `dotnet tool restore` in the repository root.
85+
86+
### Build Errors
87+
1. Verify .NET SDK is installed: `dotnet --version`
88+
2. Clean the output folder: `rm -rf docfx/_site`
89+
3. Rebuild: `cd docfx && dotnet docfx build docfx.json`
90+
91+
### Theme Not Applied
92+
The theme files should be automatically copied during build. Check that `docfx/templates/material/` folder exists and contains the template files.
93+
94+
## Plugin Notes
95+
96+
The `docfx/plugins/DocFx.Plugin.ExtractFrontMatter.dll` plugin is legacy and **not currently used** by the build process. DocFx 2.78.4 uses its built-in plugins only.
97+
98+
## Version History
99+
100+
| Date | DocFx Version | Notes |
101+
|------|---------------|-------|
102+
| 2024-01 (Previous) | 2.56.7 | Mono-based installation |
103+
| 2026-01 (Current) | 2.78.4 | .NET tool-based installation |
104+
105+
## Additional Resources
106+
107+
- [DocFx Official Documentation](https://dotnet.github.io/docfx/)
108+
- [DocFx GitHub Repository](https://github.com/dotnet/docfx)
109+
- [.NET SDK Downloads](https://dotnet.microsoft.com/download)

‎MIGRATION-CHECKLIST.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# DocFx 2.78.4 Migration Checklist
2+
3+
This checklist helps verify the DocFx upgrade is working correctly.
4+
5+
## Pre-Merge Verification
6+
7+
### Local Build Test
8+
- [ ] .NET SDK 6.0+ is installed (`dotnet --version`)
9+
- [ ] Tool restore works (`dotnet tool restore`)
10+
- [ ] Build succeeds (`cd docfx && dotnet docfx build docfx.json`)
11+
- [ ] No warnings or errors in build output
12+
- [ ] _site folder is generated with all files
13+
14+
### Theme Verification
15+
- [ ] Cyan header is present (#006064 color)
16+
- [ ] PnP Samples logo displays correctly
17+
- [ ] GitHub link in header works
18+
- [ ] Filter buttons display (All, Modernize, Data, etc.)
19+
- [ ] Search input is visible
20+
- [ ] Footer shows "Generated by DocFX with Material UI"
21+
- [ ] Navigation toggle works on mobile
22+
- [ ] Custom CSS files loaded (main.css, extra.css, filter.css, site.css)
23+
- [ ] Custom JS files loaded (main.js, filtersamples.js, loadsamples.js)
24+
25+
### Content Verification
26+
- [ ] Sample pages render correctly
27+
- [ ] Images load properly
28+
- [ ] Code blocks display with syntax highlighting
29+
- [ ] Links work (internal and external)
30+
- [ ] TOC (Table of Contents) generates properly
31+
32+
## Post-Merge Verification
33+
34+
### GitHub Actions
35+
- [ ] Workflow runs successfully
36+
- [ ] No errors in "Setup .NET" step
37+
- [ ] No errors in "Install DocFx" step
38+
- [ ] No errors in "Build docs" step
39+
- [ ] Site deploys to gh-pages branch
40+
- [ ] Published site accessible at https://pnp.github.io/script-samples/
41+
42+
### Live Site Checks
43+
- [ ] Homepage loads with material theme
44+
- [ ] Filters work correctly
45+
- [ ] Search functionality works
46+
- [ ] Sample pages display properly
47+
- [ ] Navigation between pages works
48+
- [ ] Mobile responsive design works
49+
- [ ] Footer links work
50+
51+
## Rollback Plan (if needed)
52+
53+
If issues arise, rollback steps:
54+
1. Revert the PR
55+
2. Previous version used Mono-based DocFx 2.56.7
56+
3. Restore from commit before this PR
57+
4. GitHub Actions will use old workflow
58+
59+
## Key Differences from 2.56.7
60+
61+
| Aspect | Old (2.56.7) | New (2.78.4) |
62+
|--------|--------------|--------------|
63+
| Installation | Download zip, extract, use Mono | `dotnet tool install` |
64+
| Command | `docfx build` (via Mono) | `dotnet docfx build` |
65+
| Platform | Requires Mono on Linux/Mac | .NET SDK only |
66+
| Updates | Manual download | `dotnet tool update` |
67+
| Plugin Loading | Manual copy to lib folder | Auto-loaded from package |
68+
69+
## Support
70+
71+
Questions or issues? Check:
72+
- `DOCFX-UPGRADE.md` for detailed documentation
73+
- DocFx 2.78.4 release notes: https://github.com/dotnet/docfx/releases/tag/v2.78.4
74+
- DocFx documentation: https://dotnet.github.io/docfx/
75+
76+
## Sign-off
77+
78+
- [ ] Local verification complete
79+
- [ ] Theme confirmed working
80+
- [ ] Ready to merge
81+
82+
Verified by: ________________
83+
Date: ________________

‎docfx/build.ps1‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Set-StrictMode -Version 2.0
1111
./main/docfx/generate-samplesJson.ps1 -BaseDir "./main" -OutputFile "./main/docfx/samples.json"
1212

1313
# Main DocFX build
14-
docfx build ./main/docfx/docfx.json --warningsAsErrors $args
14+
dotnet docfx build ./main/docfx/docfx.json --warningsAsErrors $args
1515

1616
# Copy the created site to the pnpcoredocs folder (= clone of the gh-pages branch)
1717
#Remove-Item ./gh-pages/*/* -Recurse -Force

‎docfx/docfx-build-local.ps1‎

Lines changed: 15 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -14,46 +14,19 @@ $baseDir = (Resolve-Path (Join-Path $runLocation "..")).Path
1414

1515
# Main DocFX build
1616
Write-Host "Building docfx..." -ForegroundColor Cyan
17-
if($IsMacOs){
1817

19-
<#
20-
Download DocFx and Install Mono if not already done.
21-
22-
- https://github.com/dotnet/docfx/releases/tag/v2.56.7
23-
- https://www.mono-project.com/docs/getting-started/install/mac/
24-
25-
Setup DocFx alias for MacOS
26-
27-
1. In VS Code, create a new file (e.g., `docfx.sh`) to hold the wrapper script.
28-
2. Add a wrapper to your script:
29-
30-
```bash
31-
#!/bin/zsh
32-
mono /path/to/docfx.exe "$@"
33-
```
34-
Replace `/path/to/docfx.exe` with the actual path.
35-
3. Make it executable in your terminal: `chmod +x /path/to/docfx.sh`.
36-
4. Move it to your PATH (e.g., `sudo mv /path/to/docfx.sh /usr/local/bin/docfx`).
37-
5. Restart the VS Code integrated terminal so `docfx` is available as an alias-like command without hardcoding paths in your scripts.
38-
39-
#>
40-
41-
Write-Host "Running docfx on MacOS using mono..." -ForegroundColor Cyan
42-
bash docfx build docfx.json --warningsAsErrors $args
43-
44-
}else{
45-
46-
<#
47-
Download DocFx and Install Mono if not already done.
48-
49-
- https://github.com/dotnet/docfx/releases/tag/v2.56.7
50-
- Set the PATH environment variable to include the path to docfx.exe
51-
- Open System Properties > Advanced > Environment Variables
52-
- Under System Variables, find and select the 'Path' variable, then click 'Edit'
53-
- Click 'New' and add the full path to the directory containing 'docfx.exe'
54-
- Click 'OK' to save the changes
55-
#>
56-
57-
Write-Host "Running docfx on Windows..." -ForegroundColor Cyan
58-
docfx build docfx.json --warningsAsErrors $args
59-
}
18+
<#
19+
DocFx is now installed as a .NET tool. To use it:
20+
21+
1. Ensure .NET SDK is installed (version 6.0 or higher)
22+
- Download from: https://dotnet.microsoft.com/download
23+
24+
2. Restore the docfx tool (if not already done):
25+
- Run: dotnet tool restore
26+
27+
3. Run docfx using:
28+
- dotnet docfx build docfx.json
29+
#>
30+
31+
Write-Host "Running docfx using .NET tool..." -ForegroundColor Cyan
32+
dotnet docfx build docfx.json --warningsAsErrors $args

‎docfx/templates/material/partials/head.tmpl.partial‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
{{#_description}}<meta property="og:description" content="{{_description}}" />{{/_description}}
2121

2222
<link rel="shortcut icon" href="{{{_appFaviconPath}}}{{^_appFaviconPath}}favicon.ico{{/_appFaviconPath}}">
23-
<link rel="stylesheet" href="{{_rel}}styles/docfx.vendor.css">
23+
<link rel="stylesheet" href="{{_rel}}styles/docfx.vendor.min.css">
2424
<link rel="stylesheet" href="{{_rel}}styles/docfx.css">
2525
<link rel="stylesheet" href="{{_rel}}styles/main.css">
2626
<link rel="stylesheet" href="{{_rel}}styles/extra.css">

‎docfx/templates/material/partials/scripts.tmpl.partial‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
22

3-
<script type="text/javascript" src="{{_rel}}styles/docfx.vendor.js"></script>
3+
<script type="text/javascript" src="{{_rel}}styles/docfx.vendor.min.js"></script>
44
<script type="text/javascript" src="{{_rel}}styles/docfx.js"></script>
55
<script type="text/javascript" src="{{_rel}}styles/main.js"></script>
66

0 commit comments

Comments
 (0)