DocFx awesome microsoft web technology framework
Docfx can be used as a static site generator, but the real value of the tool is in bringing together static documentation pages and .NET API documentation. Docfx supports both C# and VB projects (although currently the output of tool is limited to C# syntax), and relies on the long-established XML comment syntax for C# (and similarly for VB)
What is DocFx ??
Build your technical documentation site with docfx. Converts .NET assembly, XML code comment, REST API Swagger files and markdown into rendered HTML pages, JSON model or PDF files.
Why we need learn DocFx ??
Docfx is a powerful tool but easy to use for most regular use cases, once you understand the basic concepts.
Let develop your first documentation site with DocFx
For fist we need to download dotnet SDK - you can download dotnet SDK here
Download and install dotnet in to your devices, next you test with open your bash terminal and run dotnet , next you can run dotnet tool update -g docfx
Ok, its time to build your first documentation project, create a new project folder in to your devices, and run docfx init and insert your project name and others.
Now you can open on your projectfolder
Configure your DocFx project
For first configure your site open docfx.json and change this line code
"globalMetadata": {
"baseUrl": "yourdomain url here..",
"_appName": "Your doc app name",
"_appTitle": "Your title",
"_enableSearch": true,
"_lang": "en", # your default lang code
"_appFooter": "Your copyrigths text on fotter",
"pdf": true
}
Add sitemap plugin in to DocFx
Now we need to add the sitemap plugins for support your SEO , add this line code in to docfx.json
"sitemap": {
"baseUrl": "Your domain name here..",
"priority": 0.1,
"changefreq": "monthly"
},
Write your Documentation Article
What Next ??
Of course we need to write your documentation article, open docs folder and write your documentation content article.We can add meta title and description too. you can use this frontmatter format
---
title: Your title goes here...
description: Your Description goes here...
---
# Hello World
This is my article for documentation....
Setup Header Nav DocFx
Ok, next we can setup your header navigation, access on root your documentation project folder and open toc.yml file.
- name: Home
href: index.md # this is for single page link
- name: Documentation
href: docs/ # This is for access your docs folder
For single page file such index.md or about.md you can simply add markdown file name in to href
If you want to add folder in to navigation header, you can simply add your folder name , for example look like this docs/
Run DocFx
Now we can run dev mode on your local device, open terminal and run docfx docfx.json --serve
Open localhost:8080 on your web browser
Congratulations your site is live now !!
Build Production DocFx
Next if you want to upload in to your hosting, so you need to build production run this command docfx docfx.json
And now you can upload the build production folder _site in to your hosting.
Deploy to Github Page
If you want to deploy in to github pages, you just need to upload _site folder on your github repo, next you can activate your github page features.
And if you need website documentation development services with Docfx or Docusaurus, Starlight astro js and python tech MkDocs or Sphinx, our team is ready to help you.
Order Documentation Website Developer Services
Need a complete website and blog with modern JAMSTACK Static Site Generator ?? you can hire our team dev