- GitHub
README.md - MKDocs
- Obsidian
- GitBook
- Quarto
- Markdown Best Practices
- Emojis
- Badges & Icons
- Star History Graphs
- Link Team Support Numbers to WhatsApp Desktop
- Online Markdown Preview Editors
- Memes
Document right in your Git repo by creating a README.md and have your Git repo hosting platform render it as your
repo's home page - put links in it to your other markdown *.md doc files in your repo.
GitHub Markdown Syntax Documentation
MKDocs converts standard markdown files into a website.
Write in markdown with dynamic content in languages like Python.
Publish reproducible, production quality articles, presentations, dashboards, websites, blogs, and books in HTML, PDF, MS Word, ePub etc.
Publish to Posit Connect, Confluence, or other publishing systems.
Can write using Pandoc markdown, including equations, citations, crossrefs, figure panels, callouts, advanced layout etc.
Use MDL:
https://github.com/markdownlint/markdownlint
Useful for auto-linting before committing as well as in CI/CD.
See GitHub Actions - Markdown reusable workflow.
If you run into a bug that you want to ignore, you can do so by putting this comment just before the offending line or table:
<!-- mdl-disable MDnnn -->eg.
<!-- mdl-disable MD056 -->It's important not to put a bare URL because they won't by hyperlinked in some systems like MKDocs.
Use a text hyperlink:
[Some Text](https://my.domain.com/path)or if you want to show the URL wrap it in < and > to ensure it maintains compatibility to become a hyperlink:
<https://my.domain.com/path>Make links to files in the same repo, such as other markdown files or images, relative to the current markdown file so that they don't break if you change an MKDocs domain or Git repo location.
This also allows for better local navigation to click through to edit files in IDEs like IntelliJ.
Use triple backticks on separate lines to create code blocks and put a language attribute immediately after the opening backticks:
some_command -with -args 1This is much more readable than an inline code of some_command -with args 1 and then carry on with your day.
Code blocks get a Copy to Clipboard link making your life easier.
Inline code should only be for short references to command names or an arg eg.
use the git command or specify --force-with-lease option in git if you really insist on doing rebases and force
pushes.
(See also: The Evils of Git Rebasing)
This way you can click the Copy symbol in IDEs like IntelliJ and paste to your terminal, otherwise it'll copy and paste the
sample output too.
Put a language name immediately after the first triple backticks then you get syntax highlighting eg.
```groovyCompare the readability of this:
if (isCommandAvailable('gcloud')) {
echo 'Using GCloud SDK to configure Docker'
// configures docker config with a token
sh "gcloud auth configure-docker '$GAR_REGISTRY'"
}
with this having syntax highlighting:
if (isCommandAvailable('gcloud')) {
echo 'Using GCloud SDK to configure Docker'
// configures docker config with a token
sh "gcloud auth configure-docker '$GAR_REGISTRY'"
}(example from HariSekhon/Jenkins repo)
If you run IntelliJ there is also a green triangle arrow next to shell blocks to execute them with
only one click, code notebook style.
```shell
echo "execute this command"
```
echo "execute this command"Lists of emojis :shortcodes: that will be rendered on GitHub flavoured markdown:
https://gist.github.com/rxaviers/7360908
https://github.com/ikatyang/emoji-cheat-sheet
Creates standard GitHub badges in this format:
with custom writing, color and choice of Simple Icon or custom icon passed in as a base64 encoded string (see the LinkedIn Icon section below for how to do that).
Since Shields.io breaks badge components on dashes (-) you need to escape dashes by doubling them up (--).
anuraghazra/github-readme-stats
Use Simple Icons for a great selection of icons.
These can be used with the logo= parameter in Shields.io above.
marwin1991/profile-technology-icons
https://marwin1991.github.io/profile-technology-icons/
However, for icons that are not available on the Simple Icons site, or those that
got removed,
you can use the shields_embed_logo.sh script from the DevOps-Bash-tools repo.
Download the icon:
wget -nc https://raw.githubusercontent.com/simple-icons/simple-icons/e8de041b64586c0c532f9ea5508fd8e29d850937/icons/linkedin.svgshields_embed_logo.sh linkedin.svgor directly from a URL containing the icon:
shields_embed_logo.sh https://raw.githubusercontent.com/simple-icons/simple-icons/e8de041b64586c0c532f9ea5508fd8e29d850937/icons/linkedin.svgEither will result in an output like this:
logo=data:image/svg%2bxml;base64,PHN2ZyByb2xlPSJpbWciIGlmaWxsPSIjZmZmZmZmIiB2aWV3Qm94PSIwIDAgMjQgMjQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHRpdGxlPkxpbmtlZEluPC90aXRsZT48cGF0aCBkPSJNMjAuNDQ3IDIwLjQ1MmgtMy41NTR2LTUuNTY5YzAtMS4zMjgtLjAyNy0zLjAzNy0xLjg1Mi0zLjAzNy0xLjg1MyAwLTIuMTM2IDEuNDQ1LTIuMTM2IDIuOTM5djUuNjY3SDkuMzUxVjloMy40MTR2MS41NjFoLjA0NmMuNDc3LS45IDEuNjM3LTEuODUgMy4zNy0xLjg1IDMuNjAxIDAgNC4yNjcgMi4zNyA0LjI2NyA1LjQ1NXY2LjI4NnpNNS4zMzcgNy40MzNjLTEuMTQ0IDAtMi4wNjMtLjkyNi0yLjA2My0yLjA2NSAwLTEuMTM4LjkyLTIuMDYzIDIuMDYzLTIuMDYzIDEuMTQgMCAyLjA2NC45MjUgMi4wNjQgMi4wNjMgMCAxLjEzOS0uOTI1IDIuMDY1LTIuMDY0IDIuMDY1em0xLjc4MiAxMy4wMTlIMy41NTVWOWgzLjU2NHYxMS40NTJ6TTIyLjIyNSAwSDEuNzcxQy43OTIgMCAwIC43NzQgMCAxLjcyOXYyMC41NDJDMCAyMy4yMjcuNzkyIDI0IDEuNzcxIDI0aDIwLjQ1MUMyMy4yIDI0IDI0IDIzLjIyNyAyNCAyMi4yNzFWMS43MjlDMjQgLjc3NCAyMy4yIDAgMjIuMjIyIDBoLjAwM3oiLz48L3N2Zz4K
Now the default LinkedIn logo comes out dim like this:
So add the SVG attribute fill="#ffffff" to the SVG (it's just XML file) to add white filler.
sed 's|/>|fill="#ffffff" />|' linkedin.svg > linkedin_filled.svgshields_embed_logo.sh linkedin_filled.svgwhich results in a different base encoded data:
logo=data:image/svg%2bxml;base64,PHN2ZyByb2xlPSJpbWciIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48dGl0bGU+TGlua2VkSW48L3RpdGxlPjxwYXRoIGQ9Ik0yMC40NDcgMjAuNDUyaC0zLjU1NHYtNS41NjljMC0xLjMyOC0uMDI3LTMuMDM3LTEuODUyLTMuMDM3LTEuODUzIDAtMi4xMzYgMS40NDUtMi4xMzYgMi45Mzl2NS42NjdIOS4zNTFWOWgzLjQxNHYxLjU2MWguMDQ2Yy40NzctLjkgMS42MzctMS44NSAzLjM3LTEuODUgMy42MDEgMCA0LjI2NyAyLjM3IDQuMjY3IDUuNDU1djYuMjg2ek01LjMzNyA3LjQzM2MtMS4xNDQgMC0yLjA2My0uOTI2LTIuMDYzLTIuMDY1IDAtMS4xMzguOTItMi4wNjMgMi4wNjMtMi4wNjMgMS4xNCAwIDIuMDY0LjkyNSAyLjA2NCAyLjA2MyAwIDEuMTM5LS45MjUgMi4wNjUtMi4wNjQgMi4wNjV6bTEuNzgyIDEzLjAxOUgzLjU1NVY5aDMuNTY0djExLjQ1MnpNMjIuMjI1IDBIMS43NzFDLjc5MiAwIDAgLjc3NCAwIDEuNzI5djIwLjU0MkMwIDIzLjIyNy43OTIgMjQgMS43NzEgMjRoMjAuNDUxQzIzLjIgMjQgMjQgMjMuMjI3IDI0IDIyLjI3MVYxLjcyOUMyNCAuNzc0IDIzLjIgMCAyMi4yMjIgMGguMDAzeiIgLz48L3N2Zz4KPaste that generated parameter to the end of the shields.io URL, prefix with a ? if the first parameter or a &
if appended to existing parameters:
[](https://www.linkedin.com/in/HariSekhon/)Result:
Download the icon:
wget -nc https://raw.githubusercontent.com/simple-icons/simple-icons/405ef6a8c744dcf041971acfea08e0242c027fac/icons/oracle.svgChange icon to white:
sed 's|/>| fill="#ffffff" />|' oracle.svg > oracle_filled.svgGenerate the data to embed in the shields.io badge call:
shields_embed_logo.sh oracle_filled.svgOutput:
logo=data:image/svg%2bxml;base64,PHN2ZyByb2xlPSJpbWciIHZpZXdCb3g9IjAgMCAyNCAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48dGl0bGU+T3JhY2xlPC90aXRsZT48cGF0aCBkPSJNMTYuNDEyIDQuNDEyaC04LjgyYTcuNTg4IDcuNTg4IDAgMCAwLS4wMDggMTUuMTc2aDguODI4YTcuNTg4IDcuNTg4IDAgMCAwIDAtMTUuMTc2em0tLjE5MyAxMi41MDJINy43ODZhNC45MTUgNC45MTUgMCAwIDEgMC05LjgyOGg4LjQzM2E0LjkxNCA0LjkxNCAwIDEgMSAwIDkuODI4eiIgZmlsbD0iI2ZmZmZmZiIgLz48L3N2Zz4K
Put in shields.io badge to replace the icon:
[](https://oracle.com/)Result:
Usually you can get the hex colour of an icon or brand from the SimpleIcons.org website.
Click the hex colour code to copy it to clipboard.
However, sometimes the colour they have is not the colour that matches the website logo, such as is the case with Miro:
https://simpleicons.org/?q=miro
which shows this dark #050038 colour which would result in:
instead of the yellow colour that one usually associates with Miro:
In this case you can detect the colour off the website or logo yourself...
See the Visualization doc's Colours section.
You can pick the colour of an image or logo off a web page using ColorZilla to use it in a Shields.io badge.
Install the Chrome extension or Firefox extension and then just click the extension icon, picker and choose an icon or image or area from the web page.
For example, I used this to find out the exact yellow colour of the Miro.com logo as FEDD33.
This would be hard to determine by guessing the colour, and if you just picked the generic yellow colour it would come
out as this:
Whereas with the hex colour detection of the exact hex code of FEDD33 it comes out as this, which is a very diffferent
yellow:
Generate nice graphs of how your repo's star counts increased over time.
https://star-history.com/blog/how-to-use-github-star-history
May look more like a steeper rise and therefore more impressive than Starcharts.cc below.
in Dark mode using HTML:
Use Align timeline and multiple repos to compare their stars at the same relative ages:
Support mobile phone numbers should be created as WhatsApp links to allow one-click opening of chats in WhatsApp Desktop for convenience:
[+44 776 999 1234](https://wa.me/447769991234)This is not my real number. Recruiters please do not call it.
Also, if you have my real number, please do not call it.
Always message me on LinkedIn instead after reading my profile's summary bullet point criteria - it'll give you nearly everything you need to know about my availability and preferences.
In no particular order since I don't use these, I use the IntelliJ markdown preview.
