Github Wikis and Github Pages - clizarraga-UAD7/Workshops GitHub Wiki
(Image credit: girliemac.com, CC)
- Identify the different options in Github for writing Documentation projects.
- Recognize the different Markdown Languages used in each online documentation option.
- Visualize the different available edition tools.
- Construct a document in Github Wikis.
- Use the Atom Editor in Github documents preparation.
- Reproduce the process of preparation in Github Pages with the help of the Atom Editor + Github Desktop.
Prerequisites: Introduction to Github Repositories
Github Pages uses Jekyll for generating Markdown Language code that is later converted into HTML for creating static web pages. Markdown files end with the extension .md, like Readme.md.
(Image credit: Matt Cone, Markdownguide.org, CC)
Markdown is a lightweight Markup Language for creating formatted text using a plain-text editor. John Gruber and Aaron Swartz created Markdown in 2004 as a markup language that is appealing to human readers in its source code form.
There are other known markup languages that we may be unaware they are markup languages:
-
HyperText Markup Language - HTML. Created by Sir Tim Berners-Lee in 1989 while working at CERN, just before he created the first HyperText Transfer Protocol - HTTP communication application between a computer and a WWW server.
-
LaTeX. It a set of macros for interpreting TeX documents. TeX is a typesetting system written by Donald Knuth in 1978. Later Leslie Lamport built LaTeX in 1984 based on TeX to ease writing technical documents.
Github supports a class of markup languages besides Markup, with its own Markdown flavor syntax.
Google Colab uses marked.js, similar but not quite identical to the Markdown used by Jupyter and Github. Colab supports (MathJax) LaTeX equations like Jupyter, but does not allow HTML tags in the Markdown. Colab does not support some GitHub additions like emojis and to-do checkboxes.
RStudio uses R Markdown.
(Image credit: Dan O'Leary, Antisimplistic Blog, CC)
RStudio files .Rmd are converted to Markdown via knitr, then Pandoc translates the Markdown file .md into a desired output format.
Please create a new Repository in Github.com for this Workshop. We will use it to replicate some of the activities shown here.
Every Repository created in Github includes a Wiki Tab for writing code/project documentation. It includes an Editor (Write Tab) with a basic set of most frequently used functions and a Preview Tab for monitoring formatted output.
Frequent basic edition options:
- Header sizes: h1 (large), h2 (medium), h3 (small).
- The hyperlink editor
- Image insert option
- Typesetting: bold, italics and HTML code insert.
- Lists: Bullets, numbered lists
- Blockquote
- Horizontal rule
But the editor does not exclude other advanced markup functions for:
- Table editions
- Formatted code cells
- Footnotes
- More...
or if you know how to write HTML code, it can be inserted directly.
Github Wikis will allow you to build a rich documentation site, organized by sections within a document and laying out a structured collection of documents which makes them easy to navigate.
File organization, creation, edition, preview and saving is very straightforward.
As a proof of concept, please use the text generator Lorem Ipsum Text Generator to help you fill in text in your Repository Wiki.
On the other hand, it is possible for a user to create a Github Page, hosted on Github. Only one page is allowed per account, but there can be as many project pages, one per repository. There is a 1GB disk space limit per page. See Github Pages Quick Start, for instructions or select Project Site in this Menu for a Repository and follow the instructions.
A Github Page for a user account will have the URL: https://user.github.io. On the other hand a user Repository Project Site will have URL: https://user.github.io/repository_name.
The above menu will ask you to select a web page theme from a menu (recommended). Any theme can later be enriched. The menu
And you are almost done, and ready for editing the content of either the Readme.md file or an index.md file.
The following method and tips are suggested for editing the page content.
- First, clone the Github user/Repository web page on your local computer using Github Desktop.
- In your computer locate the markup file you will be editing, predefined by the selected theme.
- I will assume it is inside the /doc directory.
- Plan to create subdirectories under /doc for auxiliary files like for example: images, data, pdf, ... that your project page will store, for a well structured repository.
- Create empty markup files from the terminal or editor that will be subpages part of your web page. For example: CV.md, Infrastructure.md, Experiments.md, ... (it can be done later).
Next, it is recommended to use a text editor for creating/editing the web page content.
The Atom Editor is recommended to be used for this purpose, please download it on your local computer. Atom is a very customizable and intuitive editor part of the Github software tools ecosystem, just like Github Desktop.
Once we have installed it, we need to configure Atom for editing markdown files. The following three packages need to be installed:
- language-markdown
- markdown-writer
- markdown-viewer
To install packages in Atom from Menu open: Atom -> Preferences -> Packages -> +Install, search and install the above 3 packages.
After the installations have been completed, we can start editing the Github Pages index file: index.md or Readme.md. Within Atom, you can use the command CTRL+SHIFT+M to preview file changes.
Atom inherits many of the commands from the Emacs Editor (Same command keys are included in the Github Markup Editor and in the Linux Bash Command Line Interface).
| Ctrl-F | Move cursor Forward |
| Ctrl-B | Move cursor Backward |
| Ctrl-N | Move cursor to Next line |
| Ctrl-P | Move cursor to Previous line |
| Ctrl-E | Move cursor to End of Line |
| Ctrl-A | Move cursor to Beginning of Line |
| Ctrl-k | Send contents to memory buffer |
Explore the Atom Menu to see all available accessibility key shortcuts .
Please use again the text generator Lorem Ipsum Text Generator, to generate text and compose the Readme.md or index.md file contents.
After some edits and you are satisfied with edit changes, you can start synchronizing files from your local repository with the remote repository using Github Desktop.
After file synchronization, you can check the GitHub.io URL address corresponding to your Github page or project.
Please see the Mockup Github Documentation Project Example.
- Github Pages
- Github Pages Documentation
- Basic Writing and Formatting Syntax
- Writing Documents on Github
- Basic Markdown Syntax
- Jekyll Markdown
- Working with Tables in Github Markdown
- An Introduction to Publishing with R Markdown
- Atom Tutorial for Beginners
Created: 02/15/2022 (C. Lizarraga); Last update: 02/21/2022 (C. Lizarraga)
