Cross-references in markdown
Cross-references are links that point to other parts of the same document, such as headings, sections, figures, tables, or code blocks. They are useful for creating a logical structure and navigation for your documentation, as well as for avoiding duplication and inconsistency. However, markdown does not have a standard syntax for creating cross-references, so you need to use some extensions or workarounds to achieve them. One option is to use the HTML <a> tag with an id attribute to mark the target element, and then use a regular markdown link to refer to it. For example:
This is the first section of the document.
[Go to section 2](#section2)
Another option is to use a plugin or tool that supports cross-references, such as Pandoc, Sphinx, or MkDocs. These tools usually have their own syntax or conventions for creating cross-references, and they can also generate a table of contents, index, or glossary for your document. For example, with Pandoc, you can use the curly braces notation to create cross-references:
This is the first section of the document.
[Go to section 2](#section2)
This is the second section of the document.