Initialize
Define Base Structure
Usually, you would need to create all folders, subfolders, Markdown and Yaml files manually to build your website's navigation bar. The tricky part is to know where the Yaml files need to be created and what they should contain. As this can get a little confusing, I created a PowerShell script which does that for you. All you need to do is to define your categories in a CSV file.
An example can be found in the repo at .\Structure\Structure.csv.
Category;SubCategory1;SubCategory2;SubCategory3
Azure;Automation;Runbooks;Jobs
Azure;Automation;Runbooks;Schedules
Azure;Automation;Runbooks;Webhooks
Azure;Automation;Variables;
Azure;Functions;Authentication;
Azure;Functions;Testing;
Microsoft 365;Teams;Meetings;Join Meeting
Microsoft 365;Teams;Meetings;Organize Meeting
Microsoft 365;Teams;Collaboration;
Microsoft 365;Teams;Voice;Calling Plans
Microsoft 365;Teams;Voice;Calling Plans
Microsoft 365;Teams;Voice;Operator Connect
Microsoft 365;Teams;Voice;Direct Routing
Microsoft 365;Teams;;
Microsoft 365;SharePoint;;
Microsoft 365;Exchange;;
Microsoft 365;;;
PowerShell;Modules;;
PowerShell;Scripts;;
PowerShell;IDEs;VS Code;
PowerShell;IDEs;PowerShell ISE;
PowerShell;;;
DocFx;;;
Windows;Windows 11;OS;
Windows;Windows 11;Apps;Windows Terminal
Windows;Windows 11;Apps;PowerToys
Windows;Windows 10;Update;
CallFlows;;;
All the main categories will be included in the website's horizontal nav bar. Subcategories will be included in a main category's left vertical nav bar. Subcategories 2 and 3 will be items which can be expanded under their parent subcategory.
The CSV includes example categories for different Azure and M365 services. Adjust the CSV file to your liking by removing and adding your own categories and subcategories.
Run the Init Script
To set up your documentation site, run the following script from the VS Code workspace folder/git repo root.
.\Setup\Initialize-AwesomeDocFx.ps1 -AppTitle "Demo Docs"
Tip
The parameter -AppTitle will be the name of your website.
Caution
Run this script only once as it will delete any existing content under .\Docs\articles. New files which are not part of your Structure.csv need to be added and referenced in TOCs manually.
Check the Articles Folder
After the script has been executed, check the .\Docs\articles folder in your project workspace. The CSV and script will generate the following structure.
│───getting-started.md
│ toc.yml
│
├───azure
│ │ azure.md
│ │ toc.yml
│ │
│ ├───automation
│ │ │ automation.md
│ │ │
│ │ ├───runbooks
│ │ │ │ runbooks.md
│ │ │ │
│ │ │ ├───jobs
│ │ │ │ jobs.md
│ │ │ │
│ │ │ ├───schedules
│ │ │ │ schedules.md
│ │ │ │
│ │ │ └───webhooks
│ │ │ webhooks.md
│ │ │
│ │ └───variables
│ │ variables.md
│ │
│ └───functions
│ │ functions.md
│ │
│ ├───authentication
│ │ authentication.md
│ │
│ └───testing
│ testing.md
│
├───call-flows
│ call-flows.md
│ toc.yml
│
├───docfx
│ docfx.md
│ toc.yml
│
├───microsoft-365
│ │ microsoft-365.md
│ │ toc.yml
│ │
│ ├───exchange
│ │ exchange.md
│ │
│ ├───sharepoint
│ │ sharepoint.md
│ │
│ └───teams
│ │ teams.md
│ │
│ ├───collaboration
│ │ collaboration.md
│ │
│ ├───meetings
│ │ │ meetings.md
│ │ │
│ │ ├───join-meeting
│ │ │ join-meeting.md
│ │ │
│ │ └───organize-meeting
│ │ organize-meeting.md
│ │
│ └───voice
│ │ voice.md
│ │
│ ├───calling-plans
│ │ calling-plans.md
│ │
│ ├───direct-routing
│ │ direct-routing.md
│ │
│ └───operator-connect
│ operator-connect.md
│
├───powershell
│ │ powershell.md
│ │ toc.yml
│ │
│ ├───ides
│ │ │ ides.md
│ │ │
│ │ ├───powershell-ise
│ │ │ powershell-ise.md
│ │ │
│ │ └───vs-code
│ │ vs-code.md
│ │
│ ├───modules
│ │ modules.md
│ │
│ └───scripts
│ scripts.md
│
└───windows
│ toc.yml
│ windows.md
│
├───windows-10
│ │ windows-10.md
│ │
│ └───update
│ update.md
│
└───windows-11
│ windows-11.md
│
├───apps
│ │ apps.md
│ │
│ ├───powertoys
│ │ powertoys.md
│ │
│ └───windows-terminal
│ windows-terminal.md
│
└───os
os.md
Check the TOC Files
TOC stands for table of contents. A toc.yml file is placed in the .\Docs folder, in the .\articles folder and in each main category folder. The sub folders do not contain any TOC files. Markdown files in subfolders are referenced in the main category TOC by the relative file path.
Main TOC
The main TOC only contains references to the main category folders in .\articles.
- name: Home
href: articles/
- name: Azure
href: articles/azure/
- name: Microsoft 365
href: articles/microsoft-365/
- name: PowerShell
href: articles/powershell/
- name: DocFx
href: articles/docfx/
- name: Windows
href: articles/windows/
- name: Call Flows
href: articles/call-flows/
Articles TOC
The TOC file in .\articles only contains references to the ../index.md file located in .\Docs and to markdown files which are located in .\articles.
- name: Home
href: ../index.md
- name: Getting Started
href: getting-started.md
Main Category TOCs
The TOC files in any main category folder contain references to all markdown files inside the same folder or in subfolders of the same folder. Files which are located in a subfolder for subcategories 2 or 3 are also nested at the same level in the Yaml files.
- name: Azure
href: azure.md
- name: Automation
href: automation/automation.md
items:
- name: Runbooks
href: automation/runbooks/runbooks.md
items:
- name: Jobs
href: automation/runbooks/jobs/jobs.md
- name: Schedules
href: automation/runbooks/schedules/schedules.md
- name: Webhooks
href: automation/runbooks/webhooks/webhooks.md
- name: Variables
href: automation/variables/variables.md
- name: Functions
href: functions/functions.md
items:
- name: Authentication
href: functions/authentication/authentication.md
- name: Testing
href: functions/testing/testing.md
Tip
You can now use the existing structure to learn how the structure and TOC references work. It's a lot easier to figure it out, when you already have a prepopulated site structure.