Hosting a Help Builder Web Site using Github Pages

Github supports adding a documentation Web site to a repository which allows hosting static Web site content like that created from Help Builder output.

Pages are hosted on a domain such as:

https://rickstrahl.github.io/Westwind.Scripting/

The sub-domain name (rickstrahl) is the owner/organization of the Github repository, and the path (Westwind.Scripting) is the repository name.

To set this up you'll need to have a GitHub repository to start with and the follow the following steps:

Add Github Pages to an Existing Web Site

• Go to Settings
• Scroll down to GitHub Pages
• Choose a Source
  • Master Branch
  • Master Branch /docs folder

You have two choices for how to host your documentation:

• As part of an existing repository and tack on the docs in /docs
• Create a separate repository for the documentation

I prefer to attach my documentation site to an existing GitHub Repository in the /docs folder. What this means is that you dump Help Builders Web site output into the /docs folder.

If you choose Master Branch the assumption is that the root of the project is the root for the Web site and you'd dump the Help Builder output files into the root folder of the repository.

Build your Help File

Next you need to actually build your help file into HTML output. The easiest way to create easily copyable complete output of your Web site is to:

• Build your Project to HTML
• Choose HTML Output only
• Choose: Zip Files for Web

This creates a self contained Zip file with all the HTML files, scripts, styles and related images that can be distributed.

Copy the HTML Content into your Repository

Open the Zip file, and copy the entire contents of the file into the /docs (or root if you went with Master Branch mode) folder of your repository.

Important: Add a file called .nojekyll (no extension) into the folder you copied to. This ensures that files that start with _ as Help Builder's topics do will be copied to the content Web site.

Commit your changes and push them to GitHub.

You should now be able to navigate to:

<Owner>.githubpages.io/<Repository>

and see your help file online.