/docs-project-template

A Health Catalyst-branded sample Markdown documentation project that generates a website and/or PDFs using DocFx

Primary LanguageCSS

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.

Install DocFx

  • Create a folder in C:\Program Files called docfx.
  • Download docfx.zip from the DocFx releases page.
  • Extract the contents to C:\Program Files\docfx.

If you want to generate PDFs

  • Download the wkhtmltopdf installer.
  • Run the installer. Use the default C:\Program Files\wkhtmltopdf as the destination folder.

Add DocFx and wkhtmltopdf to PATH (in Windows)

  • 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 paste C:\Program Files\wkhtmltopdf\bin.

Build this project as a website

  • 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 cd followed 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.

For an easy internal website

Generate PDFs

  • Run docfx pdf in Windows Command Prompt.
  • The PDFs are in the newly generated subdirectory _site_pdf\docs-project-template-master_pdf in your directory.

How to change the order of articles

  • The toc.yml file in articles determines the tabs in the menu bar of the site.
  • The toc.yml files in articles/<guide-name> determine the order of articles in the site.
  • The toc.yml files in pdf/<guide-name> determine the order of articles in the PDF.

If you want to use Font Awesome icons

Font Awesome is the icon font used in Catalyst apps.

  • Install Node.js.
  • Close and reopen Windows Command Prompt. Enter cd followed 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, replace fa-plus with fa-name-of-icon found in this cheatsheet)

Other sample DocFx documentation projects

Starter project

  • Create a directory for your project.
  • Inside that directory, open Windows Command Prompt.
  • Run docfx init -q.

Sample project

Walkthroughs

See DocFx walkthroughs.

Reference

Cheatsheets

Github-flavored Markdown

DocFx-flavored Markdown

Font Awesome icons

Markdown tables generator

Code snippet language names and aliases (see Code snippets)

About the metadata header

A metadata header is required at top of each article:

---
uid: article.md
title: Article title
---
  • The uid is the same as the Markdown filename (e.g., article.md).
  • Two files with the same uid cause a build failure.

Update the table of contents

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)

Rename an article

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
  • uid in the metadata header of the .md file you renamed
  • Cross references to that .md file within the docs

Remove an article

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 a guide

  • Rename the guide's directory in:
    • <your filepath>/articles/guide-name
    • <your filepath>/pdf/guide-name (and adjust the name and href in <your filepath>/pdf/guide-name/toc.yml)
  • Search the docs for the old guide-name and replace it with the new guide-name.

Code snippets

Designate a language in code snippets

Tag the code snippet with the language to apply syntax highlighting. Language names and aliases

```xml
code```

Print code snippets in Markdown files

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")]

Callouts

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.

Icons

Insert as raw html.

Font Awesome: <i class="fa fa-plus"></i>

Glyphicons: <span class="glyphicon glyphicon-envelope"></span>

Cross references

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)