Using GitHub for Authoring​

Creating and Managing Web Content with Git, GitHub, and Markdown

– Anitha Sethumadhava Rao

If you are a writer working on a project that needs you to collaborate with multiple writers who are working on the same document, you may have faced multiple issues such as merging the changes, maintaining different versions of the same document, storing files in a location easily accessible to everyone in the team. You may have noticed that software developers work in a similar setup and face similar challenges but the problem of maintaining their code was not as daunting a task as it seems to be for documents. Yet it is true  that you can use the same solution that developers use to ease your life in managing your content by using utilities such as Git/GitHub for collaboration and Markdown as your authoring language.

In this article, we will  try to understand what these utilities have to offer!

Version Control Is Not Only for Code

Before getting into the specifics of Git, GitHub and Markdown, let us understand that in a project, everything needs to be tracked irrespective of whether it is software code, a document or any other type of content. Therefore, you will be happy to know that writers can harness the benefits of a version control system just like the developers. Utilities such as Git, GitHub, and authoring language such as Markdown enable you to do so.

What is Version Control System?

Version control system helps in maintaining a record of all files/documents and changes made to those files/documents, in a single location (or repository). Users can extract a specific version of the document if need be.  Note that a version control system is not only targeted at developers who want to store/track their code, but non-technical users can also reap the same benefits. A version control system can use a local model (users using the same file system), client-server model (users using the same shared repository), or distributed model (separate repository created for each user).

Git – The Distributed Version Control System

Git is a collaboration tool designed and developed by Linus Torvalds who led the Linux kernel project. Ever since its inception in 2005, Git has been the most popular version control system, and has dominated the version control space.

Git is a version control system that follows the distributed version control model in which your documents are stored under a repository (repo) that is equivalent to a folder on your Windows/Mac system. Unlike certain word processors, Git does not periodically save updated versions of your documents. Instead, Git will save changes only if you specifically instruct Git to do so.

git

Git helps in tracking and managing documentation changes such that reverting to any previous change is simple and easy.  In this way changes are not lost, and the same document is not overwritten with changes made by multiple writers.

Though Git is a version control system, it can also be considered as a source code management system and a revision control system. It is like a one stop solution to manage/maintain your content.

Work Offline as Seamlessly as Working Online

As writers, inspiration strikes us anywhere and we would want to pen  down our thoughts irrespective of whether we are hooked to the Internet or not. This means that we do not want our work to be disrupted whether we are online or offline. Git provides the facility to work on your local system while you are on the move by allowing you to commit, browse, merge, or create branches. The next instance you are connected to the Internet, you can instruct Git to push these changes to the main branch.

Why Use Something Like Git?

Using Git to manage your next writing project gives you the ability to view multiple drafts at the same time, see differences between those drafts, and even roll back to a previous version. And if you’re comfortable doing so, you can then share your work with others on GitHub or other central Git repositories.

For instance, consider two writers in the same project updating the same page for a document. If the first writer makes changes to the document and uploads the changed document while the second writer has also uploaded a changed document. In an ideal situation, one of the writers will lose their changes but with Git that does not happen. Though both writers upload the same document with their changes, Git maintains separate copies of each document. Anyone can decide to merge changes in both the documents or later, even decide to revert to the previous version of the document because Git has anyways stored a snapshot of each change made to the document. 

GitHub – Enhancing Your Git Experience

GitHub is a cloud-based version control service that incorporates Git’s version control features. While Git is a distributed version control software that you can install locally on your system, GitHub is a web-based utility where files are stored on a GitHub Web server. Unlike Git which is a command-line utility, GitHub provides a graphical user interface to view and manage files placed under a repository. If you are a writer authoring content in text-based authoring formats, such as Markdown or HTML, you can avail the additional benefit that GitHub offers, that is of a Web publishing engine. This integrated publishing engine in GitHub renders your content to the Web, and provides a unique URL to access it too. So GitHub is not just a revision control repository but also a Web publishing engine. 

With GitHub, you can either configure a repository as private  or configure the repository as public, thus allowing anyone on the Web to download and make changes to the repository. However, these changes will need to be sent as change requests and you can decide if you want to accept and merge the changes into your file.

Git and GitHub – Are They Same or Different?

Git and GitHub are similar to the extent that both provide version control services, but GitHub is much more than that. In addition to the version control feature, GitHub provides several security and collaboration features like, Wikis, and task management tools for each project. If your intention is only to work locally, then Git is your best option, but if you want to collaborate with multiple writers globally, then GitHub is the solution for you.

Markdown – The Popular Text-Based Authoring Format

In 2004, John Gruber and Aaron Swartz created the Markdown language with an intention to provide a language that was easy to write and read. Markdown was developed in such a way that it did not appear as if the Markdown file was marked up with tags to depict formatting styles like in an HTML file.

Markdown is a plain text formatting language and also a tool to convert plain text to a valid HTML file. Markdown provides several simple tags that you can use to define formatting such as bold, underline, italics, lists, and so on. However, the presence of these tags does not interfere with the readability of the document and you can read a Markdown document with the same ease as you would read the same document when it is converted to HTML.

 

markdown

If you want to author a document in Markdown, text editors compatible with Markdown authoring are freely available on the Web for the Windows and Mac Operating systems. If you do not want to install a Markdown editor on your system, you can work on an online editor, such as Dillinger (see Figure below) that provides a HTML preview of your Markdown document in the left pane of the editor.

Due to the widespread popularity of Markdown, several implementations were developed such as the GitHub Flavoured Markdown (GFM) developed by GitHub in 2017. GFM is the default markdown format used for documents stored in a GitHub repository unless you want to override the formatting by defining your own template and stylesheet.

One of the advantages of using Markdown formatted files in GitHub is that it is easy to compare files for changes because Markdown is a plain text file, like a developer’s code. This makes merging documentation changes also easy, a feature that is prevalent in the coding world!

Is Markdown Good for Writers?

Off late many writers wish to maintain blogs of their own and Markdown is the best format to use for creating Web content. To create a blog of your own, create a document and save it with .md or .Markdown, which is the Markdown extension. Further, create a repository on a cloud-based version control system, such as GitHub, and copy your .md file into that repository. GitHub provides a personalized URL when the .md file is hosted in HTML format. This way you can focus your energy in writing quality content and leave the HTML rendering nuances to GitHub.

Markdown is platform agnostic in the sense that you need not be forced to use the format of your editor. For instance, to create a .md file, you can use any editor installed on your system or use GitHub’s inbuilt Markdown editor.

As Markdown is a lightweight plain text format, the learning curve is not much, and anybody can start using it quickly.

While advantages of Markdown are manifold, a probable disadvantage may be that you need to remember different Markdown tags as there is no button that you can click to get the required formatting.

Final Thoughts

Up until now, we have understood what Git, GitHub and Markdown are, and how these utilities are useful to writers as much as they are for developers. As discussed previously, if you want to use these utilities to maintain your documents and effortlessly post them in HTML format onto the Web, you can use Git for the version control purposes, and use GitHub for hosting your .md documents to the Web. Alternatively, you can use GitHub for both version control and Web hosting activities. While GitHub enables you to create and edit Markdown files, it is better to edit the .md files locally on your system. Therefore, install a Markdown editor (such as Notepad++ or Atom) on your system so that you can edit the .md files locally. To push locally edited files into the GitHub repository, you will need the Git bash client. This utility is installed when you install Git on your system. For detailed instructions on Git and Git Bash Client, see the Git documentation at https://git-scm.com/book/en/v2. Now that you have obtained a fair understanding of the framework in which you can author, manage and publish your document on the Web, and get your own personalized URL too, get blogging!

About the Author

Anitha s. Rao is a passionate Technical Writer who holds a Master’s Degree in Computer Application. She loves to read and write about technology and enjoys explaining complex technical concepts in simple words. In addition to writing, she spends her free time reading, gardening, and pursuing her passion for dance.

1 Comment
  • Vijay Kulkarni
    Posted at 11:26h, 21 April Reply

    Informative and helpful article

Feel like talking? Share your comment...

%d bloggers like this: