Walkthrough Part I: Generate a Simple Documentation Website
By completing this walkthrough, you'll become familiar with the workflow of
docfx and the general principle of organizing documents inside
docfx. You will finish this walkthrough with a static website that can be published to any host service. Download the files used in this walkthrough here.
Step1. Setup DocFX
- Download docfx.zip and unzip it to
PATHso that the command
docfxcan be directly called from everywhere for convenience. (For example, for Windows,
Step2. Init a DocFX project
- Create a new folder
- Start Command Line under
docfx init -q. This command generates a
docfx_projectfolder with the default
docfx.jsonfile under it.
docfx.jsonis the configuration file
docfxuses to generate documentation.
-qoption means generating the project quietly using default values, you can also try
docfx initand follow the instructions to provide your own settings.
docfx init will create a set of subdirectories, used to hold the source files required for generating a DocFx website:
- \src - contains the optional .NET language project files (*.csproj), which contain the type information used to generate managed API docs.
- \api - if the \src subdirectory contains project files, DocFx will generate .YML metadata files from them and store them here. The .YML files contain the structured type information, including any
///comments provided in the source code. A stub landing page (index.md) and TOC (toc.yml) are generated as well. You learn more about this process in Walkthrough Part II: Adding API Documentation to the Website.
- \apidoc - contains Markdown files used to overwrite the auto-generated text from
- \articles - contains Markdown files used to provide ancillary conceptual documentation, for explaining how to use your API documentation, etc.
- \images - contains image files referenced from Markdown files.
Step3. Build our website
docfx docfx_project/docfx.json. Note that a new subfolder
_site is generated under that folder. This is where the static website is generated.
Step4. Preview our website
The generated static website can be published to GitHub pages, Azure websites, or your own hosting services without any further changes. You can also run command
docfx serve docfx_project/_site to preview the website locally.
8080 is not in use,
docfx will host
8080 is in use, you can use
docfx serve _site -p <port> to change the port to be used by
Congrats! You can now see a simple website similar to:
Step5. Add a set of articles to the website
details3.md. If the files reference any resources, put those resources into the
In order to organize these articles, we add these files into
articlessubfolder. The content of
toc.ymlis as below:
- name: Introduction href: intro.md - name: Details 1 href: details1.md - name: Details 2 href: details2.md - name: Details 3 href: details3.md
So now our folder layout is:
|- index.md |- toc.yml |- articles | |- intro.md | |- details1.md | |- details2.md | |- details3.md | |- toc.yml |- images |- details1_image.png
Run Step3 and Step4 again, and the website is now: .
Notice that more items are added to the sidebar for Articles nav page. The title inside the sidebar is exactly what we set in the
In this walkthrough, we built a website from a set of
.md files. We call these
.md files Conceptual Documentation. In walkthrough part 2, we will learn to add API Documentation to our website. The API Documentation is extracted directly from .NET source code. In a series of advanced walkthroughs, we will learn advanced concepts in
docfx, such as cross reference between articles, external reference to other documentation sets, etc. We will also learn to customize our websites, from theme to layout to metadata extraction.