Docfx is a static site generator that uses C# as its templating language. It is an exceptionally powerful tool, offering immense flexibility and customization options for creating a documentation website. Moreover, Docfx is user-friendly and easy to learn. This section covers the basics of Docfx configuration for the Stride Docs website, while the creation and updating of content are detailed in our Content section.
After reviewing various static site generator options, we decided to continue using Docfx, particularly in light of the release of the new
modern Docfx template. This template leverages Bootstrap 5.3 and has recently introduced a dark theme feature.
Packages and Dependencies
Currently, we are not utilizing any additional packages.
The configuration for Docfx is located in the
en\docfx.json file. This file contains all the necessary settings for the Docfx build process.
Contents of the Configuration File:
- API Sources: Specifies the Stride path and selected projects for API documentation generation
- Global Metadata: Contains global configuration settings for the documentation build
- File Metadata: Defines folder sections to be processed for documentation generation, such as Manuals, Tutorials, etc.
- Resource - Pass Through Files: Lists files that are copied directly to the output folder without processing
- Other Configuration: Explore the file for additional configuration options
For more details on configuration options, visit the Docfx Configuration Documentation.
Docfx currently does not support global data like 11ty. At present, Mustache can only be used in templates.
The folder structure plays a vital role in the documentation generation process, as it determines the output of the build. The structure is organized as follows:
.github: Contains GitHub Action workflows
_site: The output build folder (excluded in
.gitignoreand used for deployment)
en: Contains the English language documentation
en\api: Automatically generated folder from the Stride API
en\contributors: Documentation for contributors
en\diagnostics: Diagnostic pages referenced by Stride solution warnings in the IDE
en\examples: Additional content for C# XML comments, which are merged into API documentation and linked by uids
en\includes: Markdown files whose content can be included in multiple
.mdfiles across the documentation.
en\manual: Documentation for the manual
en\media: Main media assets
en\ReleaseNotes: Documentation for release notes
en\template: Docfx assets for minor template customization, including CSS and JS files
en\tutorials: Documentation for tutorials
jp: Japanese language documentation, translated from the English version (currently not updated)
wiki: GitHub wiki content - Excluded from the build process and used only for wiki deployment. This section will be decommissioned as the content has been moved to Stride Docs.
en\*.md: Markdown content pages
en\*.yml: Table of content files
en\.nojekyll: A flag file for GitHub Actions
en\docfx.json: Docfx configuration file
en\filterConfig.yml: Rules for API exclusion
en\languages.json: Configuration file for languages
Non Docfx Files
appsettings.json: Configuration file for ASP.NET Core.
appsettings.Development.json: Development-specific configuration file for ASP.NET Core.
build-all.bat: Batch file used in GitHub Actions CI/CD to build all documentation using
BuildDocs.ps1: PowerShell script responsible for building documentation. Refer to pipeline for details.
OldDocsFix.ps1: Temporary PowerShell script for fixing old documentation.
Program.cs: Startup file for ASP.NET Core.
run.bat: Batch file to run
BuildDocs.ps1in interactive mode.
run-fix.bat: Temporary batch file to run
Stride.Docs.csproj: ASP.NET Core project file.
Stride.Docs.sln: ASP.NET Core solution file.
Stride.Docs.csproj.user: User-specific ASP.NET Core project file.
versions.json: Configuration file managing versions of Stride documentation.
web.config: Configuration file for IIS deployment.
This project includes the Visual Studio solution
Stride.Docs.sln, allowing you to edit the files using the Visual Studio IDE.
We utilize the default layout provided by the
modern template, as specified in
All includes are located in the
/_includes folder. These are reusable markdown snippets that can be incorporated into multiple pages.