Ever since I started playing around with GitHub a few years ago and came across Markdown, I have fallen in love with it. I try to use Markdown whenever possible for various document editing purposes - READMEs, blogs, API documentation, and more.
Over the years, I have noticed that more and more websites and programs are providing support for Markdown. From the initial encounters with GitHub and Jekyll to platforms like Jian Shu and CSDN, I have learned some "tips and tricks" from well-crafted documents. Therefore, this article is not an introduction to the basic syntax of Markdown, but rather a collection of relatively advanced techniques that can help you explore more possibilities with Markdown.
Note: Most of the following techniques rely on the compatibility of Markdown with certain HTML tags, so they may not be fully supported on all websites and software. The main reference for compatibility is GitHub.
Line Breaks in Table Cells#
You can use the <br /> tag from HTML to achieve line breaks in table cells.
Example code:
| Header1 | Header2 |
| ------- | -------------------------------- |
| item 1 | 1. one<br />2. two<br />3. three |
Example result:
| Header1 | Header2 |
|---|---|
| item 1 | 1. one 2. two 3. three |
Mixing Images and Text#
Use the <img> tag to insert images and specify the align attribute.
Example code:
<img align="right" src="https://raw.githubusercontent.com/mzlogin/mzlogin.github.io/master/images/posts/markdown/demo.png"/>
This is an example image.
The image is displayed to the right of N paragraphs of text.
N depends on the height of the image.
Lorem ipsum.
Lorem ipsum.
By now, the text should not be affected. This line should extend just below the image, so I need to make it long enough to ensure that the effect is visible on different screens.
Controlling Image Size and Position#
The standard Markdown image syntax ![]() does not allow you to specify the size and position of the image. It relies on the default image size and is left-aligned.
However, sometimes you may want to reduce the size of the original image or center-align it. In such cases, you still need to rely on HTML tags. You can use the <div> tag with the align attribute to center-align the image, and the width and height attributes to control the size of the image.
Example code:
Default image display:
Controlled image display:
<div align="center">
<img
width="65"
height="75"
src="https://raw.githubusercontent.com/mzlogin/mzlogin.github.io/master/images/posts/markdown/demo.png"
/>
</div>
Doesn't it look much better?
Using Emoji#
This is an extension to the standard Markdown syntax introduced by GitHub. Using emojis can make your text more lively.
Example code:
My friends and I are all laughing. :smile:
Example result:
My friends and I are all laughing. 😄
For more available emoji codes, refer to https://www.webpagefx.com/tools/emoji-cheat-sheet/.
Indenting at the Beginning of a Line#
Indenting with spaces and tabs directly in Markdown will be ignored when rendered. To achieve indentation, you can use HTML escape characters to add spaces at the beginning of a line. Use   for half-width spaces and   for full-width spaces.
Example code:
  Spring has arrived, and it's the season of rejuvenation for all things.
Displaying Mathematical Formulas#
If you are using GitHub Pages and Hexo, you can refer to http://wanguolin.github.io/mathmatics_rending/ to elegantly display mathematical formulas (not as images).
If you are working on a README or other places in a GitHub project, the only solution I have found so far is to use images. Here is a convenient method for inserting formula images:
- Enter the LaTeX formula in the input box on the webpage at
https://www.codecogs.com/latex/eqneditor.php, for example:$$x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}$$. - Copy the URL Encoded content from the bottom of the webpage. For example, the formula mentioned above generates:
https://latex.codecogs.com/png.image?%5Chuge%20%5Cdpi%7B300%7D%5Cdpi%7B200%7D%5Cint%20%5Cfrac%7B1%7D%7Bx%7D%20dx%20=%20%5Cln%20%5Cleft%7C%20x%20%5Cright%7C%20+%20C. - Use the above URL to insert the formula image in your document, like this:
Task Lists#
On websites like GitHub and GitLab, in addition to ordered and unordered lists, you can also use task lists, which are very suitable for scenarios where you need to list items.
Example code:
**Shopping List**
- [ ] Disposable cups
- [x] Watermelon
- [ ] Soy milk
- [x] Coca-Cola
- [ ] Xiao Ming
Automatic Table of Contents#
Sometimes, when maintaining a long document, you may want to automatically generate a table of contents (TOC) based on the headings in the document. It should also update automatically when the headings change, reducing workload and minimizing errors.
If you use the Vim editor, you can use the vim-markdown-toc plugin to perfectly solve this problem.
[[toc]]
If you use other editors, you can usually find corresponding solutions. For example, the markdown-toc plugin for Atom, or the MarkdownTOC plugin for Sublime Text.
Conclusion#
Alright, that's it for this round of tips and tricks. I hope you find them helpful.
If you found this article useful, feel free to follow my channel for more helpful content.
References#
https://raw.githubusercontent.com/matiassingers/awesome-readme/master/readme.md
https://www.zybuluo.com/songpfei/note/247346
https://www.youtube.com/channel/UCOE6Ckq2Pip08Ia1Zg6dUGA