Effortless Documentation with DocFX: Build, Deploy, and Scale Without Writing Code

From Source to Site: Secure, Scalable Docs with DocFX

Convert Markdown and YAML into a comprehensive documentation site — effortless and code-free! Well, maybe just a touch of JSON scripting.

Have you ever struggled with documentation? What if I told you that you could build a professional-looking docs site without writing a single line of code? Enter DocFX, a powerful tool that transforms Markdown and YAML into a structured, searchable, and beautifully rendered documentation site.

Getting Started

Before diving in, let’s grab our power tools:

• PowerShell for command-line execution

• DocFX for site generation

• Markdown/YAML for content structuring

• Azure DevOps or GitHub Repos (optional) for version control

Step-by-Step Guide

• Install DocFx using PowerShell, or Dotnet commands.

dotnet tool install docfx --global
docfx init -q

• Customize Your Configuration Modify docfx.json to define content sources, templates, and metadata.

{
    “build”: {
        “content”: [
            {
                “files”: [
                    “*.{md,yml}”,
                    “**/*.{md,yml}”
                ]
            }
        ],
        “resource”: [
            {
                “files”: [
                    “.attachments/**”,
                    “images/**.{ico,png}”,
                    “*.{ico,png}”,
                    “scripts/**.{js}”,
                    “web.config”
                ]
            }
        ],
        “globalMetadata”: {
            “_appTitle”: “apurvghai.com”,
            “_appLogoPath”: “images/logo.png”,
            “_appFaviconPath”: “favicon.ico”,
            “_enableSearch”: true,
            “_enableNewTab”: true,
            “_gitContribute”: {
                “repo”: “https://github.com/<yourrepoUrl>”,
                “branch”: “master”
            },
            “_appFooter”: “Built using DocFx”
        },
        “template”: [
            “default”,
            “templates/material”
        ],
        “postProcessors”: [
            “ExtractSearchIndex”
        ],
        “force”: true,
        “dest”: “docs”,
        “globalMetadataFiles”: [],
        “fileMetadataFiles”: [],
        “markdownEngineName”: “markdig”,
        “noLangKeyword”: false
    }
}

• Organize Your Files Structure your folders to align with your documentation needs.

- firstDocFxSite
- images
- src
 - AnotherFolder
   - Sub-Article-1.md
   - Article-1.md
   - Getting-Started.md
 - docfx.json
 - index.md
 - toc.yml

• Create a Table of Contents (TOC) Define navigation using toc.yml for seamless browsing.

• Add following content into your root\toc.yml

- name: apurvghai.com 
  href: something.md

• Add following content into your root\src\toc.yml

    - name: Intro 
      href: ../index.md 
    - name: Getting Started 
      href: Getting-Started.md 
    - name: Article 1 
      href: Article-1.md 
      items: 
        - name: Sub-Article-1.md 
          href: AnotherFolder/Sub-Article-1.md 

• Build & Preview Locally Run:

docfx docfx.json --serve --force

Build using Azure DevOps Pipelines

For advanced users looking to automate website deployment to Azure, configuring a release pipeline with YAML offers a streamlined approach.

By leveraging Azure DevOps Pipelines, you can set up a fully automated workflow that builds, validates, and deploys your DocFX-generated site effortlessly.

Below is a YAML pipeline snippet that can be used to build the site, particularly useful for a Pull Request build.

- task: AzureCLI@2
  inputs:
    scriptType: ‘pscore’
    scriptLocation: ‘inlineScript’
    inlineScript: |
      # Install the tool
      dotnet tool install docfx --global
      
      docfx docfx.json --build --warningAsErrors true

Let your documentation speak for itself—securely, automatically, and effortlessly.