GitHub, Markdown, Visual Studio Code and git to share knowledge

Dear Community, I know the title of this blog sounds like “Buzzword Bingo”. But I can assure you: that’s not the case 😉

I actually wanted to take a look at Visual Studio Code (VSC) based on this blog. Thanks to Lars Hvam, Marcello Urbani and other developers, there is support for ABAP. At this point, many thanks for their work.

During my first steps, I was initially enthusiastic about another topic, which I would like to report on today. So I will tell my experiences with VSC and ABAP in another blog.

Purpose

Today, the focus is on GitHub, Markdown, Visual Studio Code and git in combination. The goal is to use these tools to share knowledge and work together to expand the knowledge. What knowledge? Whatever you want … probably something in the development area 😉

I saw this approach for the first time with the Clean ABAP Style Guide and was impressed. Perhaps nothing special for the rest of the developer world, I was surprised by the possibilities to work together on an online document (without a Wiki).

Now I would like to share my first steps and experiences. Maybe someone is surprised by the possibilities of the tools and platforms, too? 🙂 Apart from that, topics like “git” will also play a role in the SAP ERP context. More on this in the blog “Git-enabled Change and Transport System“.

Since the interaction of the tools and platform is complex, I have included many links in this blog. You should definitely visit the linked pages.

I am sure that there are also many experts on the subjects here in SAP Community Network. Please add information to my blog if I have not presented something correctly or adequately 🙂

Steps

Here is a brief overview of the steps. The steps are described in more detail in the following chapters. I recommend some time to read and try. Maybe with your work colleagues?

1. Create an account on GitHub and create your first repository.
2. Make first steps with Markdown.
3. Install VSC on your computer and enhance it with some extensions to work with Markdown documents.
4. Install git on your computer and use it in combination with GitHub and VSC.

GitHub

Description of GitHub

I got to know GitHub while working with abapGit. GitHub is a platform on which you can manage software development projects in public or private repositories. More information about GitHub can be found in this article “What Exactly Is GitHub Anyway?“. You need an account to work with GitHub. The first steps are explained in this “Hello World” article.

Use of GitHub in our example

For our example, we need a new, initialized repository. In this context, “initialized” means that we had a “README.MD” file generated when the repository was created. I called my test repository “scn_blog_test”. The repository is our public online folder, so to speak, where we store our knowledge to share.

README.MD in my example

Markdown

Description of Markdown

Documents created in the markup language Markdown can be managed in a GitHub repository. The practical thing about Markdown is that the syntax can be learned quickly and a document with Markdown syntax is very easy to read. Here’s an example and here is a Markdown cheat sheet.

# Headline 1

## Headline 2

**Hello SAP Community**

* unordered list item 1
* unordered list item 2

Markdown example

Use of Markdown in our example

One advantage of GitHub is that Markdown documents can be edited online on GitHub with its syntax in a text editor and can also be immediately interpreted as HTML. At the same time, the repository has all the advantages of GitHub, such as traceability of all changes. The initialization of our repository has already created a Markdown file, namely “README.MD”. This looks like this when editing in GitHub:

README.md file content

If we add our example from above and save, it looks like this:

enhanced Markdown example

Ok, now we have the technical language in which we can format our knowledge.

Visual Studio Code

Description of Visual Studio Code

Visual Studio Code is a free development environment from Microsoft. Different programming and markup languages are supported. Including Markdown. First steps with VSC are described here.

Use of Visual Studio Code in our example

With the two free extensions “Markdown All in One” and “markdownlint” VSC becomes a nice Markdown editor. Markdownlint in particular helps to create a compliant markdown document.

With the preview function in VSC, you can edit the raw data in split-screen mode and at the same time see the HTML display.

Split-screen with Editor and Preview of a local test file

More information about working with Markdown in VSC can be found in this article. A display of Markdown documents in the GitHub style is possible with the extension “Markdown Preview Github Styling” (I was happy with the preview of VSC).

Ok, with the VSC we now have a nice editor that supports us while writing down our knowledge.

Git

Description of Git

I really like the Wikipedia description of git:

“Git is a distributed version-control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files. Its goals include speed, data integrity, and support for distributed, non-linear workflows.”

I think that says a lot and “in any set of files” also means Markdown files. Good for us 😉

Use of Git in our example

I downloaded and installed git from this page. Here is the documentation. Some setup was needed, check this page. Git can be used in VSC (check this link).

First of all, we create a local copy of the GitHub repository on our computer. For this we use the command “git: clone” in VSC, enter the URL of the repository, choose the storage location in our file system and have the repository added to the VSC workspace (check this link).

Now you can edit the local “README.MD” file. Any changes to the local copy will be recorded.

changed content in README.md

Then we have to “stage changes” in Source Control (plus sign next to the filename “README.md”).

Then execute “commit” (checkmark, see link) and “synch” (check link).

As a result, the changes to the local copy are now also carried out online in the GitHub repository.

changed README.md on GitHub

Thats all for now. Goal achieved. The next interesting step is described here. That would be the topic of another blog.

Benefits

Let’s take a look at the benefits:

1. There is something to celebrate because you have successfully tried something new 😉
2. With this simple example, you can take your first steps with tools like VSC. Then the journey continues, of course. Thousands of options are waiting.
3. There are various repositories on GitHub that are used to exchange information via Markdown documents. Clean ABAP style guide is e.g. such a repository. You are welcome to work on such repositories.
4. Through the above steps you have a GitHub account. The way to abapGit is not far anymore. Just try 🙂
5. <Add your benefits via comment>

Best regards, thanks for reading and have a great time!

Michael

P. S.: I am sure that the constellation of GitHub, Markdown and git can also be made with Eclipse.