(*) This document was generated by ChatGPT based on an outline prepared for the “Markdown for BDSL Laboratory” guide.
Introduction
Markdown is a lightweight markup language for creating structured documents using plain text. Instead of focusing on the visual appearance of a document, Markdown describes its logical structure through a simple and intuitive syntax. Common document elements—including headings, paragraphs, lists, tables, hyperlinks, images, mathematical equations, and source code—can be written using only a small set of plain-text symbols. As a result, Markdown documents remain readable even without dedicated software and can be edited using virtually any text editor.
Compared with conventional word processors, Markdown provides several important advantages for scientific research. Since Markdown files are plain text, they are lightweight, platform-independent, and compatible with version control systems such as Git. They can also be converted into many other formats, including HTML, PDF, Microsoft Word, and presentation slides. These characteristics make Markdown particularly suitable for collaborative research, software development, and reproducible scientific documentation.
In the Bioinformatics and Data Science Laboratory (BDSL), Markdown is the standard format for documenting research activities. Project documentation, laboratory protocols, analysis reports, meeting minutes, software documentation, GitLab Wiki pages, and README files are all primarily written in Markdown. Using a common documentation format improves consistency among projects, facilitates collaboration between laboratory members, and enables efficient tracking of document revisions through Git.
The appearance of a Markdown document depends on the application used to render it. Although the core syntax is standardized, different platforms may support additional features or display documents differently. Throughout this guide, we focus on the syntax and conventions adopted in the BDSL. Unless otherwise noted, all examples are based on GitLab Flavored Markdown (GLFM), which is the primary Markdown implementation used in our laboratory.
One important exception is the BDSL homepage, which is built using WordPress. WordPress employs its own block-based editor rather than GitLab Flavored Markdown. Nevertheless, most standard Markdown syntax is compatible with WordPress, and Markdown documents can usually be copied into WordPress with only minor modifications.
This guide introduces the fundamental components of Markdown and demonstrates how they are used in laboratory documentation. The objective is not to describe every available Markdown feature, but rather to provide the practical knowledge necessary for creating clear, consistent, and maintainable documents within the BDSL.
Components of Markdown
Markdown consists of a small number of document elements that can be combined to create rich and well-organized documents. The following chapters introduce each component in detail.
Document Structure
A Markdown document is organized hierarchically using headings and paragraphs. Good document structure improves readability and allows automatic generation of a table of contents.
Topics include:
- Markdown files
- File organization
- Heading hierarchy
- Logical document organization
Headings
Headings define the hierarchical structure of a document.
Topics include:
- Heading levels (`#`–`######`)
- Section organization
- Best practices for heading hierarchy
Paragraphs
Paragraphs are the fundamental building blocks of text.
Topics include:
- Paragraph separation
- Line breaks
- Horizontal rules
Text Formatting
Markdown supports several methods for emphasizing text while maintaining readability.
Topics include:
- **Bold text**
- *Italic text*
- ***Bold italic***
~~Strikethrough~~- Superscripts and subscripts (when supported)
Inline Code
Inline code highlights commands, filenames, variables, or short code fragments.
Typical applications include:
- Terminal commands
- File paths
- Program names
- Configuration options
- Function names
Blockquotes
Blockquotes are useful for displaying quotations, notes, warnings, or important remarks.
Typical applications include:
- Important notes
- Warnings
- Tips
- Literature quotations
Lists
Markdown supports several types of lists for organizing information.
Unordered Lists
Useful for
- Bullet points
- Feature lists
- Summaries
Ordered Lists
Useful for
- Procedures
- Experimental protocols
- Step-by-step instructions
Nested Lists
Useful for organizing complex information into multiple levels.
Task Lists
GitLab supports interactive task lists.
Example applications include:
- Project management
- TODO lists
- Manuscript revision tracking
- Experimental checklists
Scientific Documentation
Markdown is particularly useful for scientific writing because it integrates text, figures, mathematics, and source code within a single document.
Tables
Tables organize structured information in a compact format.
Typical uses include:
- Experimental metadata
- Statistical summaries
- Sample information
- Software versions
Images
Images can be inserted directly into Markdown documents.
Topics include:
- Figure insertion
- Relative image paths
- Image organization
- Figure captions
Code Blocks
Large code fragments should be placed inside fenced code blocks.
GitLab automatically performs syntax highlighting for many programming languages, including:
- Python
- R
- Bash
- YAML
- JSON
- C/C++
- JavaScript
Mathematical Equations
GitLab supports LaTeX-style mathematical notation.
Applications include:
- Mathematical formulas
- Statistical equations
- Matrix notation
- Chemical equations
- Scientific symbols
Mermaid Diagrams
GitLab supports Mermaid, allowing diagrams to be generated directly from text.
Common diagram types include:
- Flowcharts
- Sequence diagrams
- State diagrams
- Class diagrams
- Entity relationship diagrams
- Git graphs
- Timeline diagrams
- Mind maps
- Directory trees
Because diagrams are defined using text, they can be version controlled alongside the rest of the document.
References and Links
Markdown provides several mechanisms for connecting documents and citing external resources.
Hyperlinks
Links may refer to
- Websites
- GitLab pages
- Documents
- Images
- Downloads
- Email addresses
Footnotes
Footnotes provide supplementary explanations without interrupting the main text.
Typical uses include:
- Additional explanations
- Definitions
- References
Cross References
Large documentation projects often consist of many Markdown files.
Cross references allow navigation between
- Sections
- Documents
- Figures
- Tables
- External repositories
Collaboration
One of the greatest advantages of Markdown is its integration with Git and collaborative development platforms such as GitLab.
Version Control
Markdown documents are plain text, allowing Git to record every modification.
Benefits include:
- Complete revision history
- Comparison between versions
- Recovery of previous versions
- Collaborative editing
Comments and Discussions
GitLab enables collaborative review through inline discussions.
Laboratory members can
- Review documents
- Leave comments
- Suggest modifications
- Resolve discussions
- Track review progress
Best Practices in the BDSL
To maintain consistency across projects, the following practices are recommended.
- Use descriptive headings to organize documents.
- Keep paragraphs concise and focused on a single topic.
- Prefer relative links over absolute links within repositories.
- Store figures in dedicated directories such as `figures/` or `images/`.
- Use fenced code blocks for all source code.
- Write mathematical expressions using LaTeX notation.
- Organize documents according to the logical structure of the project.
- Commit documentation changes regularly to Git.
- Review Markdown rendering in GitLab before committing major revisions.
- Maintain consistent formatting throughout the repository.
Summary
Markdown is the standard documentation language used throughout the BDSL. Its simplicity, readability, and compatibility with Git make it an ideal format for research documentation, collaborative writing, and software development. By mastering a relatively small set of Markdown features, laboratory members can produce professional, maintainable, and reproducible documentation for projects of any size.
The following chapters describe each Markdown component in detail and provide practical examples using GitLab Flavored Markdown.