Typora and GitHub Pages for your Docs/Blog

You can publish your documentation or blog using GitHub pages.

Step 1 - Github Repository

You can add documentation to any repository that you have on GitHub. What you need to do is add html files directly to the root of one of your branches for your repo, or put a series of them plus related resources into a folder called docs in one of your branches. One of your html files should be called index.html

GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.

This means that you can, if you like with a pro account, create a private repository where you may have source code related to a project that you do not want to make available, but contain documentation regarding that project contained within that repo be made publicly available.

So, you need to have a GitHub repository for your content.

If you already have a GitHub repository and you have cloned a local version of your repo to your computer, you can skip this step.

For the purposes of this video, I am going to be simply creating a repository with a README file that I will then edit using Typora and let Typora generate the html files for me that I will commit and push back to my repo so that GitHub pages will publish the documentation as a web page.

I have a GitHub pro account so I am able to make my repo private, yet have the documentation still published with pages.

The first thing I am going to do is create a new repository and let GitHub generate the README file for me.
1. Give your repo a name
2. Provide a description
3. If you have a pro account, you can make your repo private, otherwise it has to be public
4. Add a README file.
5. Click on Create Repository

I prefer to use Typora as a markdown editor and let it generate the required html.

Step 1 - Clone the repository to your local computer

If you are following along with this example, you will have to clone your repo to your local computer.

To clone this repo to my desktop, I am going to use the command line and, I have already installed the official GitHub CLI using


xxxxxxxxxx
https://cli.github.com

There are a number of ways to install it, but I choose to use Homebrew on my M1 Mac mini


xxxxxxxxxx
brew install gh

With it installed, I can go back to the repository that I have just created and Copy the GitHub CLI code from the Code menu

Next I am going to cd to my desktop or any location where you want to clone the repository to and command in terminal. I am going to cd to the desktop and clone the repo there.


xxxxxxxxxx
cd ~/desktop

gh repo clone StewartLynch/GitHub-Pages

I get a warning that I need to first run gh auth login because I am not already logged in to my GitHub account. When I do that, I am presented with a number of questions.
1. I want to log in through GitHub.com
2. I will use HTTPS
3. I can authenticate Git with my GitHub credentials so I answer Y
4. Next I can either authenticate with a browser, or paste in a personal access authentication token, but I could authenticate using a browser as well, but I keep my access token for this computer readily available as I need it for Xcode, so I can paste it in.
This logs me in to my account.
1. Now that I am logged in, I can issue that clone command again
```
xxxxxxxxxx
gh repo clone StewartLynch/GitHub-Pages
```
When it is complete you will find the repository in your specified location, and in my case it is the desktop with the README file inside.

Step 3 - Create your html documentation

With your repository now locally on your computer, you can create your documentation any way you like to do that. I like to use Typora, which is a MarkDown editor that has a great feature that will convert markdown documents to html.

I have a video on this that will demonstrate the feature set. Although it is now a paid application, I am happy to pay the price because I have not found anything that is as simple and intuitive to use for generating Markdown and I use it all the time for creating README files for all of my Xcode repositories and for doing things like scripting this video.

You can find that video here: https://youtu.be/Yq6u6Z1yuco

Tip

To make it easier to include images in documentation, I recommend that you:

Choose Typora > Preferences... and allow it to copy any pasted images into a folder called images that is relative to the current folder.

For the purposes of this tutorial, I am just going to use this README file to create the script that I use for creating the video.

If you paste any image into the document, an Images folder gets created automatically when the first one is pasted.

Choose a different Theme if you like from the Themes menu. Additional themes are available from the Typora themes gallery. https://theme.typora.io

When you are happy with your documentation, you can save it as html. In Typora, choose File > Export > HTML but instead of calling the file README.html, call it index.html and this will serve as the main page for your documentation/blog

Step 4 - Commit and Push to GitHub

Once you have done your export to html, you need to update your remote repository. This can be done on the command line in 3 or 4 steps.

Make sure you CD into that repo folder which in my case is GitHub-Pages and it is relative to the desktop where I already am.
```
xxxxxxxxxx
CD GitHub-Pages
```
Next, because I have added files like the index.html and folder of images and changed the README file I need to add them before committing.
```
xxxxxxxxxx
git add .
```

You must commit them to the local repository with a comment before pushing them up to the repository.


xxxxxxxxxx
git commit -m "converted README to html"

Finally, you can push the back to GitHub


xxxxxxxxxx
git push -u origin main

Step 5 - Enable Pages

With your html files now on GitHub, you can now enable the pages option for this repository.

Open your GitHub repository and click on the Settings menu
On the left sidebar, click on Pages
Next, you need to select a Source for your html pages.
1. Select the branch. Ours is on the main branch as we only have one branch
2. Select the sub directory of the branch. You have two choices, it can either be the root, as we have done, or you could have created a directory called docs on the root of that branch and stored your html files within that directory.
3. Click on Save
This will reveal the link to your web page.
Note: It may take a short time before the page is live.