This starter Markdown documentation project supports Health Catalyst teams that want to begin managing their documentation as Markdown files. It uses the open-source tool DocFx to generate a website and PDFs. The output aligns with Health Catalyst's Fabric.Cashmere style guide.
For Markdown cheatsheets and details on things like icons, callouts, styles, etc., see Reference.
The following instructions apply to Windows, but DocFx and this project are also supported on Linux and macOS.
- Create a folder in
C:\Program Filescalleddocfx. - Download
docfx.zipfrom the DocFx releases page. - Extract the contents to
C:\Program Files\docfx.
- Download the wkhtmltopdf installer.
- Run the installer. Use the default
C:\Program Files\wkhtmltopdfas the destination folder.
- Control Panel > Change View by to Small icons > System > Advanced system settings > Environment Variables...
- Under the System variables section, scroll to Path. Select it and click Edit....
- Depending on what version of Windows you're using, you see either a long string of values separated by semicolons or values in a vertical list.
- If you see a long string of values, append to the end:
;C:\Program Files\DocFX;C:\Program Files\wkhtmltopdf\bin - If you see values in a vertical list: Click New and paste
C:\Program Files\DocFX. Click New again and pasteC:\Program Files\wkhtmltopdf\bin.
- If you see a long string of values, append to the end:
- On this project's Github page, click Clone or download > Download ZIP. Extract it to wherever is convenient. This is the directory you'll work in. Don't extract it to
C:\Program Files\docfx. - Open Windows Command Prompt. Enter
cdfollowed by the filepath to your directory. For example,cd C:\docs-project-template-master. - Run
docfx build docfx.json --serve. - In your browser, go to http://localhost:8080.
- Find the website files in the newly generated subdirectory
\_sitein your directory. - Push the site to an Azure web app (see Local Git Deployment to Azure App Service).
- Set up authentication to be internal visitors only with Azure Active Directory (see Configure your App Service app to use Azure Active Directory login).
- Request a healthcatalyst.com or healthcatalyst.net domain name from IT (for example, mydocs.healthcatalyst.com).
- Run
docfx pdfin Windows Command Prompt. - The PDFs are in the newly generated subdirectory
_site_pdf\docs-project-template-master_pdfin your directory.
- The
toc.ymlfile inarticlesdetermines the tabs in the menu bar of the site. - The
toc.ymlfiles inarticles/<guide-name>determine the order of articles in the site. - The
toc.ymlfiles inpdf/<guide-name>determine the order of articles in the PDF.
Font Awesome is the icon font used in Catalyst apps.
- Install Node.js.
- Close and reopen Windows Command Prompt. Enter
cdfollowed by the filepath to your directory. For example,cd C:\docs-project-template-master. - Enter
npm install --save. - How to include an icon in a Markdown file:
<i class="fa fa-plus"></i>(in this example, replacefa-pluswithfa-name-of-iconfound in this cheatsheet)
- Create a directory for your project.
- Inside that directory, open Windows Command Prompt.
- Run
docfx init -q.
- Clone DocFx seed.
See DocFx walkthroughs.
A metadata header is required at top of each article:
---
uid: article.md
title: Article title
---- The
uidis the same as the Markdown filename (e.g.,article.md). - Two files with the same
uidcause a build failure.
Update references in:
- <your filepath>/articles/guide-name/toc.yml (the order of articles in the site)
- <your filepath>/articles/pdf/guide-name/toc.yml (the order of articles in the PDF)
Change:
- The name of the .md file
- References in <your filepath>/articles/guide-name/toc.yml and <your filepath>/articles/pdf/guide-name/toc.yml
uidin the metadata header of the .md file you renamed- Cross references to that .md file within the docs
Remove:
- The .md file
- Any associated images
- Cross references to the deleted .md file.
- The article from the table of contents (toc.yml) files
- Rename the guide's directory in:
- <your filepath>/articles/guide-name
- <your filepath>/pdf/guide-name (and adjust the
nameandhrefin <your filepath>/pdf/guide-name/toc.yml)
- Search the docs for the old guide-name and replace it with the new guide-name.
Tag the code snippet with the language to apply syntax highlighting. Language names and aliases
```xml
code```For long code examples, store the code in its native format in <your filepath>/articles/guide-name/snippets and reference it like this:
[!code-json[Main](snippets/example.json "Example")]Add a note, tip, warning, important, or caution callout.
> [!NOTE]
> This is a note.
> [!TIP]
> This is a tip.
> [!IMPORTANT]
> This is an important statement.
> [!CAUTION]
> This is a caution.
> [!WARNING]
> This is a warning.
Insert as raw html.
Font Awesome: <i class="fa fa-plus"></i>
Glyphicons: <span class="glyphicon glyphicon-envelope"></span>
| Location | Notes | Pattern |
|---|---|---|
| To a place in the same article | [link name](#heading-name) |
|
| To another article | If you want the link name match the title of the article you're referencing Link name is the title in the metadata header |
@uid |
| If you want to customize the link name | [link name](articles/guide-name/article.md) |
|
| If you want the reference inside parentheses | (<xref:article.md>) |
|
...(see [link name](articles/guide-name/article.md)). |
||
| If the .md file is in a higher directory | [link name](../../folder/article.md) |
|
| To a specific place in another article | @uid#heading-name |
|
[link name](articles/guide-name/article.md#heading-name) |