👩🏻‍🚀 Creativitas ⏰ 05 June 2024

🔖 microsoft docfx learn jamstack static site generator

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

Order Static Site Generator Web Services