Get Up Get Down Get Hip With Git Markdown- GitHub Writing Format
If you want to make sure you're rolling with the "cool kids"- you gotta get hip to the lingo- in this case it's GitHub Flavored Markdown.
GitHub Flavored Markdown
Per GitHub's docs*,
"GitHub combines a syntax for formatting text called GitHub Flavored Markdown with a few unique writing features.".
There's a 'way' to properly write when doing so on GitHub-
Almost a right of passage for many a developer/ programmer/ Master Hacker Supreme/ computer enthusiast- you know that they are legit if you spot 'em doing it proper.
It's the secret phrase/ pass word to get into the VIP lounge- guarded by security and bouncers, the one door in the back alley that leads to where the Normies only dream of gaining access to...
...the far fetched tails told of the happenings beyond those closed doors.
To enter, a mastery in Markdown is a necessity.
Learning GitHub Markdown, Where to Start
...but not so fast, maybe try the latter if you've never before...
If you've already gotten some basics then you can start here or continue down below to really start from the beginning... do the courses! Otherwise flex what you got and carry on this next part- make sure you comer back and link your README in the comments- would love to see em.
Learn by Creating a README for your GitHub Profile
Good thing GitHub lays out the basics to the advanced in a manner that is easy to consume- even advising us how we can flex our new found knowledge by creating a 'README' for our GitHub profile-
https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github
Basic Writing and Formatting
Or better yet- "Basic Writing and Formatting"- Start right at the beginning with text sizing/ heading size... how to bold, italic, strike through, sub/ superscript, nested- getting more into it as you scroll down with quotes, links, color variants, comments, tables dot dot dot...more...https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
The Basics but in a Course
Or even better- a quick course(less than 1 hour ) that goes through much(all ) of what is covered in the previous link, but in a course format. I find this a better way to sink in all the new found knowledge-In the course you learn:
- How to add headers
- Add images
- Add code examples
- Make task lists
- Merge pull requests
If You Haven't Before, Intro to GitHub - Do this First-
Before all else- do the Introduction to GitHub Course for a sturdy foundation.
As a prerequisite they (the ALL GIT, who else? ) do ask that you are familiar with pull requests as well as how to edit files in GitHub. If you aren't familiar with those, then it is recommend you take the Introduction to GitHub course, first.
I strongly suggest in doing so, since Markdown is a huge part of it. You'll use Markdown to create a short file that can be used as your profile README - the course is less than an hour- knowledge gained is invaluable.
https://github.com/skills/introduction-to-github
Just like this Emoji "cheat sheet" for future reference*
Advanced Markdown:
Having gone through the above, you've pretty much got all you need to bust into the VIP lounge- If you want to shine though... there's some more to learn.
The nity gritty- everything GitHub Markdown...I mean it, everything...
https://github.github.com/gfm/
The next link provides a very thorough resource-
Which also gives us the online "Dingus"
https://daringfireball.net/projects/markdown/dingus <- If anything, this is a great "cheat sheet" of sorts for Markdown, since it's all pretty much there above the fold.
There used to be a http://www.aaronsw.com/2002/html2text/ but, after over a decade of nothing...It appears... to be.... non existent.... unless you know better. If you do, please leave a comment below.
* Mermaid Diagrams-
https://github.com/mermaid-js/mermaid
https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams
I think that's plenty for now- but, if there is anything of interest others would like to share/ contribute, please do leave a comment.
Some Extras...
Ok- maybe some more- since, while attempting to find an image for "MarkDown" there was so much on subject content that I came across-
Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.https://daringfireball.net/projects/markdown/
Which also gives us the online "Dingus"
https://daringfireball.net/projects/markdown/dingus <- If anything, this is a great "cheat sheet" of sorts for Markdown, since it's all pretty much there above the fold.
There used to be a http://www.aaronsw.com/2002/html2text/ but, after over a decade of nothing...It appears... to be.... non existent.... unless you know better. If you do, please leave a comment below.
Now to get... "Fancy"
For the most part, just a way to fancy up your GitHub content, in another way can be an incredible asset to your projects providing updated visualizations to better interpret data and the like... and, since things like diagrams typically would be done in image editors- these would consume a great deal of time and creative energy- this can now be done automatically, matching your data/ project in real time.Creating Diagrams-
The following is a great resource- most, if not all diagrams are image based or previously required much coding for the diagram to be dynamic. If a update happened, the image would have to be edited in its respective software. What Mermaid Diagrams provides is a way to introduce many- and I say many, maybe even all- diagrams/ a visual way to display our data, or process, or... In this case within GitHub. So, update the data in your GitHub repository and the diagram is updated. Maybe a Gannt Chart showing time line of project.. easily updated for all, automatically in parallel with updates made by all... A huge time saver.* Mermaid Diagrams-
https://github.com/mermaid-js/mermaid
https://github.com/mermaid-js/mermaidhttps://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams
* Live Diagram Creation using Mermaid- https://mermaid.live/edit#pako:eNpVkEFrg0AQhf_KMqcW4h_wUGi0zSUlgeZU9TDo6C5xd5Z1JAT1v3eNtLRzmuF97zG8CWpuCFJoe77VGoOoS146Fee1yHQwg1gcKpUkL_OBRFl2dJ_V_unAatDsvXHd88bvV0hl03HFSIk27rpsUvbwnxzNKi-O6IV99Ve53HhWb4U56xj_X9GBouu9aDFtMakxqAxDBTuwFCyaJr4-rYYSRJOlEtK4NtTi2EsJpVsiiqPw593VkEoYaQeBx05DzOuHeI2-QaHcYBfQ_iAe3Rez_YWoMcLhY-vqUdnyDSATZqk
* Using Mermaid Chart- https://www.mermaidchart.com/play#pako:eNpVjLEOgjAURX_lpZMO_QEGEynKQqIDW-3wUottlL6mNCGG8u-CLHrXc86dmKa7YQXrXjRqizFBW908LDtKYaMbUo-DAs4PuTYJevLmnaHc1QSDpRCcf-w3v1wlEFOzagaSdf45b0h8-4s3GSrZYEgU1C9pR8pwku5ql_t_YqNZqrPssOiQa4wgMCo2fwBnHTpc
* Need some inspiration? One of many- scroll up/ down... Many examples that can be used directly in markdown- https://kroki.io/examples.html#excalidraw
* More Examples: https://mermaid.js.org/syntax/examples.html
* The below are links to videos that Mermaid Diagrams provides as resources to get familiar with its use- I apologize in advance if you get as annoyed as I did...
* A ridiculous 'How To' for using Mermaid Diagrams in GitLab- https://www.youtube.com/watch?v=SQ9QmuTHuSI&t=438s&ab_channel=GitLabUnfiltered
* "Just Learned this 8 Hours Ago..."- https://www.youtube.com/watch?v=7_2IroEs6Is&t=207s&ab_channel=WorldofZero
* https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-githubI think that's plenty for now- but, if there is anything of interest others would like to share/ contribute, please do leave a comment.
Some Extras...
... because we can never get enough
Ok- maybe some more- since, while attempting to find an image for "MarkDown" there was so much on subject content that I came across-