doc/articles/uno-development/docfx.md
Uno Platform's docs website uses DocFX to convert Markdown files in the articles folder into html files.
Normally when you add a new doc file, you also add it to articles/toc.yml. This allows it to show up in the left sidebar Table of Contents on the docs website.
DocFX supports extended Markdown syntaxes that are treated specially when converting to html.
You can declare a specially-styled blockquote like so:
> [!NOTE]
> This is a Note, showing how to declare notes.
This is how it looks when converted to .html:
[!NOTE] This is a Note, showing how to declare notes.
Use pre-formatted blockquotes when you want to call special attention to particular information.
The following note types are supported:
> [!NOTE]
> ...
> [!TIP]
> ...
> [!WARNING]
> ...
> [!IMPORTANT]
> ...
> [!CAUTION]
> ...
DocFX can generate tabs. Make sure to follow the syntax specification precisely.
Markdown:
# [WinUI](#tab/tabid-1)
`WinUI.Namespace`
# [Uno Platform](#tab/tabid-2)
`Uno.Namespace`
---
Html output:
WinUI.Namespace
Uno.Namespace
The check_toc script checks for dead links in the TOC, as well as Markdown files in the 'articles' folder that are not part of the TOC. At the moment it's not part of the CI, but contributors can run it locally and fix any bad or missing links.
Sometimes you may want to run DocFX locally to validate that changes you've made look good in html.
Before building the documentation locally, ensure you have the following installed:
brew install docfx
choco install docfx
[!NOTE] On Windows, run the
choco install docfxcommand from an elevated PowerShell prompt (Run as Administrator) to avoid permission errors.
Use a Node.js version manager (nvm or nvs) with the version specified in the .nvmrc file in the doc folder.
# Using nvs
nvs use
# Or using nvm
nvm use
Then install the npm dependencies:
cd doc
npm install
"Implemented views" are documentation pages that are generated from the Uno source code to describe how specific APIs are implemented across platforms. They are consumed by DocFX as part of the full docs build, but most day-to-day documentation changes (guides, how-tos, etc.) do not require regenerating them.
You typically only need to generate implemented views when you are working on the tooling that produces them, or when you want to validate a full local DocFX build that includes these generated pages. For most contributors, this step can be safely skipped.
If you do need to generate them:
Uno.UI-Tools.slnf solution filter in the src folder with Visual Studio.Uno.WinAppSDKSyncGenerator project. Under the 'Debug' tab, set Application arguments to "doc".Uno.WinAppSDKSyncGenerator as startup project and run it. It may fail to generate the full implemented views content; if so, it should still nonetheless generate stubs so that DocFX can run successfully.[!NOTE] By default, the build does not fail on DocFX errors (it prints them in the console). This is for simplicity since you don't need the implemented views for most documentation work. To test DocFX and break on error, run the
npm run strictcommand.
The easiest way to build and serve the documentation locally is using npm scripts:
cd doc
# Start development server with live reload
npm start
This command will:
http://localhost:3000 (or the next available port)# Build for production (minified, no source maps)
# Run this before committing changes
npm run build
# Build and serve with production settings
npm run prod
# Build with strict error checking (fails on DocFX errors)
npm run strict
# Clean generated files
npm run clean
[!IMPORTANT] Always run
npm run buildbefore committing changes to ensure the production assets are properly generated and minified.
If you prefer to run DocFX directly without npm:
1- Navigate to the doc folder.
2- Run DocFX with the configuration file:
docfx docfx.json
3- The generated HTML will be in the _site folder.
After building with DocFX directly, you can serve the documentation using a local HTTP server.
dotnet-serve is a simple command-line HTTP server:
1- Install dotnet-serve:
dotnet tool install --global dotnet-serve
2- Navigate to the _site folder and start the server:
cd _site
dotnet serve -o -S
This will start a server with HTTPS and open the browser automatically.
For more information about dotnet-serve usage and options, please refer to the documentation.
The documentation website uses Algolia DocSearch for search functionality. The search is configured in doc/templates/uno/partials/scripts.tmpl.partial.
The DocSearch implementation is already integrated into the documentation templates and will work automatically when you serve the documentation locally using npm start or after building with npm run build.
The search configuration includes:
PHB9D8WS99platform#docsearch (located in the sidebar)When running the documentation locally:
1- Start the development server:
cd doc
npm start
2- Open your browser to the local server URL (typically http://localhost:3000).
3- The search box should appear in the left sidebar.
4- Type a search query to test the search functionality.
[!NOTE] The search uses the production Algolia index, so search results will reflect the content currently deployed to the live documentation site, not your local changes. To see your local content in search results, your changes need to be deployed to production and the Algolia index needs to be updated.
The DocSearch initialization is handled by JavaScript in the scripts.tmpl.partial file:
MutationObserver watches for the #docsearch element to be added to the DOMIf the search isn't working as expected:
#docsearch element exists in the DOM (it's in the sidebar's .sidefilter div)If needed, you can also run a script that will give you a performance summary for the documentation generation.
To run the script on Windows:
crosstargeting_override.props is not defining UnoTargetFrameworkOverriderun-doc-generation.cmd script; make sure to follow the instructions