Finally A Website On Github.io
Creating content for websites can be very painful from shell/ terminal. While the terminal can be used for executing commands, running the site and for many other purposes, we still need a visual code editor for creating advanced visual components and written content for webpages. For that we either need a desktop enviroment with code editors installed or an online editor with visual editing.
Some popular code open source (free) editor for a desktop type environment are
Visual Studio Code by Microsoft,
Atom by Github and
Sublime Text by Jon Skinner, Will Bond. These come with very advanced code editing features and are very easy to use.
In this tutorial however we are not going to use a desktop enviroment so rather than installing a local editor we will switch to web based editor. Some examples of hosting services that provide such editors are
Most of these services accept github logins as accounts (another good use of your github ID). These come integrated with a shell (running on a virtual machine) that we can use just like any linux server for development purposes only. If you want to host a website or need a VM you will have to purchase subscription according to their plans and pricing.
For this tutorial we will use GCP - Google Cloud Platform. Please refer to the Setup Tutorial for Google Cloud Console.
Google Cloud Code editor
Once you have setup your cloud shell environment fire up the terminal in your browser and make a clone of the repo for the website we created in the previous tutorial
git clone https://github.com/username/username.github.io
You will be able to visualize the repository and its folder structure in the google cloud code editor.
Setup a mkdocs project
We will use our github repo
username.github.io directory to initialize the mkdocs project.
mkdocs new . # initialize 'mkdocs.yml' and docs/ in current directory
At this point your directory structure will look like this: 2 new items will be added to the current directory:
docs/ directory is created with an
index.md file in it and
mkdocs.yml config file.
. ├── docs │ └── index.md └── mkdocs.yml
# mkdocs.yml -- MkDocs configuration, all *.md files relative to docs/ site_name: You Awesome Website name theme: name: material site_url: https://username.github.io
We will be using Google's material theme (same as this tutorial website). This is one of the most popular themes on the we and very easy to get started with. It also comes with in-built search capabilities within the document hosted in the sites. Read: Material Features
You can also try
readthedocs theme that come packaged with mkdocs. Just update the theme name and rebuild your website to view the changes.
We will already have a
docs/ directory to write files into. All the markdown documents need to be placed inside this as
[filename].md files. As usual we should start with an
index.md file (already created by default) as entrypoint to this directory. If you create subdirectories it is recommended that you have an
index.md in each of them as entrypoints. However mkdocs will parse you files in order and show them in the navivgation menu even if you dont have an index file in subsequent subdirectories inside the
Lets create 2 document like this
To see the changes we made and how our site looks like we can start a local server inbuilt in mkdocs using
python -m mkdocs serve # OR simply mkdocs serve # if mkdocs is in your $PATH
This will generate an output
INFO - Building documentation... INFO - Cleaning site directory [I 190106 11:53:50 server:298] Serving on http://127.0.0.1:8000 [I 190106 11:53:50 handlers:59] Start watching changes [I 190106 11:53:50 handlers:61] Start detecting changes
Take a nope of the port : 8000.
If you are using a local desktop just navigate to http://127.0.0.1:8000 on your browser to view your mkdocs website.
If you are using GCP (google cloud console) you should configure preview port to 8000 to view it from google cloud console.
In this tutorial we are using GCP so we need to configure preview port to 8000 and click preview link. This will open a new browser tab/ window and you can view your website.
mkdocs -serve by default enables live editing so you can see changes live while you are editing the markdown documents.
Build the documents
Once we have finalized all the markdown documents we need to build it. Building means generating the
html files from the mkarkdown document we wrote in the
python -m mkdocs build # OR simply mkdocs build # if mkdocs is in your $PATH
The above statement will generate the following output
INFO - Cleaning site directory INFO - Building documentation to directory: /home/your/username.github.io/site
Note the subdirectory
site/ is created in your mkdocs project which will contain all the html files that are ready to be hosted on any webserver.
Example: For 3 markdown documents
markdown.md written in
docs/ the following show the directory structure created after building the site.
tree -L 2 . ├── docs │ ├── helloworld.md │ ├── index.md │ └── markdown.md ├── mkdocs.yml └── site ├── 404.html ├── assets ├── helloworld ├── index.html ├── markdown ├── search ├── sitemap.xml └── sitemap.xml.gz
In this example you will notice that for every markdown file (
xxx.md) document in
docs/ there is a corresponding html file (
xxx.html) created in
site/. If you have subdirectories in the markdown docs directory, it will be replicated in the site directory.
Publish them on Github.io
site/ directory contains your final wesite. You can copy its contents to anyserver and point the url to it path. Your website will be up and running.
If you want to host this
site to be at your
username.github.io home then you have to clean up the repo and put all the contents of
site/ directory at out repo root directory.
In this tutorial however we have a different entrypoint
index.html at the home of the website. We will upload the entire repo to github and so we need to manually point to the
site/ directory from our landing page
index.html which we created in the previous tutorial.
Let update the repo
git add --all git commit -m "site updated" git push
Check your online repo at github.com and erify your site is up at http://username.github.io/site. Note the
/site added to your URL since we are hosting from a subdirectory at inside your repo root directory. Your website should be up and it will identical to what you previewed at the GCP console.
Now lets link this site to our
index.html landing page which we created in the root directory (previous tutorial)
Use the code editor or terminal to edit the index.html file in root dir
# from root dir: username.github.io/ nano index.html
Update one the
navigation links on top right in the same way. Replace the text or
# in the
href= tags with approproate links to your pages.
<li class="Navigation-listItem"> <a href="site/" class="Navigation-link"> My Documents </a> </li>
The link will show as 'My Document' and point to http://username.github.io/site using the tag link in
Finally add, commit and push to github
# shortcut for all git commands: in nano editor - write message, save and exit nano git add --all && git commit --all && git push
And that is it. You can continue developing the site and add pages.
Summary of the steps
- add markdowns in
- build them (from the mkdocs root where the mkdocs.yml exists)
- commit and push the repo to github
- view the website at http://username.github.io/site