Skip to content

Latest commit

 

History

History
75 lines (52 loc) · 1.94 KB

overview.md

File metadata and controls

75 lines (52 loc) · 1.94 KB
Raw

An Azure DevOps pipeline task to turn your Azure DevOps wiki into an DocFX website.

This allows to to create a public documentation website with the nice wiki editing tools of Azure DevOps.

Supports

  • Links between pages
  • Images
  • Mermaid diagrams
  • Running the website in a subdirectory: all the links are made relative
  • Copies only referenced attachments

Does not support

  • Nothing that I currently know of.

Template

This project contains a modified version of the default DocFX template to get everything to work.

To use your own docfx template:

  • Copy the template files in this repository to a directory in the source folder. For example ".docfx_template".
  • Modify the template to your needs.
  • Specify the directory name in the 'Template directory name' pipeline task argument.

Hiding content

To hide content, surround it with ::: private and ::: (on their own line). E.g.:

Content publicly visible in the DocFX website.

::: private
This will not be visible in the DocFX website.
::: 

This will be visible again.

If you put ::: private at the start of the page and do not close it, the whole file will be ignored.

Usage

You can use this task in build and release.

Build

With a azure-pipelines.yml build file below, an artifact with the website files will be created. This you can release to a webserver.

trigger:
- main

pool: 
  vmImage: 'windows-latest'

steps:
- task: AzureDevOpsWikiToDocFx@1
  inputs:
    SourceFolder: '$(System.DefaultWorkingDirectory)'
    TargetFolder: '$(System.DefaultWorkingDirectory)/docfx'
- task: DocFxTask@0
  inputs:
    solution: 'docfx/docfx.json'
- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: '$(System.DefaultWorkingDirectory)/docfx/_site'
    ArtifactName: 'drop'
    publishLocation: 'Container'

Release

Works quite the same as in a build pipeline.