Technical Articles
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?
- Create an account on GitHub and create your first repository.
- Make first steps with Markdown.
- Install VSC on your computer and enhance it with some extensions to work with Markdown documents.
- 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:
- There is something to celebrate because you have successfully tried something new 😉
- 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.
- 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.
- Through the above steps you have a GitHub account. The way to abapGit is not far anymore. Just try 🙂
- <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.
Hi Michael Keller,
nice description of the Markdown, VS Code, Github. I totally agree that it is a very nice way to share knowledge. I used it last semester to write the script for one of my lectures (not publicly available, yet) and really liked it. I will definitely stick to it for the future. Maybe with one exception, I'll try to change VS Code to Vim.
For me the best part was the possibility to integrate the feedback of other people (students in my case) back into the documents.
Christian
Brilliant idea! The students already come into contact with a new technology (markdown) via the lectures and influence the design, structure and content. Some kind of positive crowdsourcing.
I used to work with "vi". If you know the keyboard shortcuts, it is really fun. And it worked wonderfully via SSH.
Hi,
this is perfect.
I created a repository about SAP Development topics which is 100% markdown. With those 2 VS-code extensions it will be much easier to work on them ( when I finally have the time to work on them…. )
Do you know if VS-Code supports GitHub nativley – so that I am able to clone and work on the repository and push it directly into the repository or do I have to install Github Desktop for it?
Thanks!
Bastian
I typically use the command line, but version control is built-in, https://code.visualstudio.com/docs/editor/versioncontrol, if thats the question?
For pull requests(not git native) see https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github
Thanks. I "needed" the second one for pull requests.
Here is the link to the repository of Bastian: https://github.com/DennstedtB/SAP-Development-Info-Hub
I think Sandra Rossi is working on a information repository too https://github.com/sandraros/Quality-SAP-Q-A-wiki?
Thanks Michael. I confirm. Started a few weeks ago. Slowly growing and deciding how it will be...
Great post Michael. ?
I totally agree with you, that this is a great way to share knowledge. I do this myself. I've made the resource lists for the presentations I held at TechEd Barcelona available there, and I have also a "Today I learned"(til) repository, that I don't have a good routine of adding to. ? The theory behind it, is that we have a repo to quickly add small nuggets we learn, the moment we identify them, and push them up. As a way to capture all the little things that we tend to forget, and that don't deserve a whole blog post. There are lots of great TILs out there. You can find many of them by googling "Today I learned site:github.com".
One of the benefits of using Github, is that people can "star" your repo, to get notifications when you update it with new information.
You can also customise your pinned repos, to push the one you want to share, front and center. That way people see them, the moment they land on your profile page.
Thanks for the additions. GitHub is really a "little home" for developers. It's very exciting to live all the platforms and communication options. My life as an ABAP developer has definitely been enriched.
And lots of great options for focusing on the content while writing the markdown, and adding steps for presentation, eg. https://docs.abapgit.org/guide-install.html is generated by jekyll based on https://github.com/larshp/abapGit/blob/master/docs/guide-install.md
Another exciting option is http://asciidoc.org/, which is somewhere in between markdown and latex, making it good for writing documents and storing the source in git.
Thumbs up for the reference on AsciiDoc. I've already worked with it - great.
You might be interested to know that Markdown and Github is what we use to create all the tutorials on developers.sap.com as well. You can even see the repository behind the site here: https://github.com/SAPDocuments/Tutorials
Thanks for the hint. It's nice to see what you can do with GitHub, Markdown, etc. in practice. Hopefully an inspiration for even more interesting projects.
Two thumbs up because one is not enough??
There is a Bob Ross quote that applies to lightweight markup languages like Markdown
You can focus on content itself, and let the output "compiler" format it for you.
I can share some benefits that I had with Markdown:
You can do anything with it: bundle it with MDwiki and you can publish entire sites / quick guides even on a network drive to target intranet only, no dedicated HTTP server required.
Put Pandoc into the mix and you can create presentations too.
Hi Thales,
the rebels need the right tools to reach everyone else with their words and scriptures.
For everyone who doesn’t know Bob Ross, here is the wiki entry. Highly recommended. Great quote, Thales. I saw Bob on TV at night when I were in the bar too long. Helps to fall asleep.
Perhaps we should use a few quotes from Anthony Bourdain in the future
Â
I'll put into my backlog, but I must warn that it have a lower priority than Pulp Fiction ones.