> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Demo Identify the Basic Formatting Syntax
> Practical guide to Markdown and MDX formatting for README files with examples, tips, and best practices for headings, lists, tables, code blocks, and GitHub rendering.
This lesson shows how to apply common Markdown (and MDX) formatting to a README. It walks through practical examples you can paste directly into your README source to improve readability on GitHub and other Markdown renderers.
A few MDX-specific tips for editing READMEs rendered as MDX:
* Wrap snippets that include curly braces or angle-bracket placeholders in backticks, for example: `` `{{workflow.name}}` `` or `` `https://localhost:` ``.
* Avoid placing raw JSON or object literals inline; use fenced code blocks to ensure correct rendering and parsing.
When adding examples with placeholders (e.g., ``, ``) or template variables (e.g., `{{inputs.param}}`), always wrap them in backticks to prevent the MDX parser from interpreting them as JSX or template syntax.
## Quick reference
Use this short reference for common Markdown elements and how to use them in README files.
| Element | Syntax | Example | |
| --------------- | -----------------------------------: | --------------------------------------------------- | ---------------------------- |
| Heading | `#` through `######` | `# Heading 1` | |
| Blockquote | `>` | `> This is a quoted block.` | |
| Inline emphasis | `*italic*`, `**bold**`, `` `code` `` | `This is *italic* and **bold**. Use `inline code`.` | |
| Horizontal rule | `---` | `---` | |
| Unordered list | `-` or `*` | `- Item A` | |
| Ordered list | `1.` | `1. First item` | |
| Task list | `- [ ]` / `- [x]` | `- [x] Complete step` | |
| Table | Pipes \` | `and dashes`-\` | See the Tables section below |
| Hidden comment | HTML comment | `` | |
## Hiding lines with HTML comments
Use HTML-style comments in the README to keep content visible only in the source but hidden when rendered on GitHub:
```markdown theme={null}
```
These are useful for leaving notes, TODOs, or editing reminders inside your README file.
## Headings
Create headings with the hash (`#`) character. More hashes produce smaller headings:
```markdown theme={null}
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
```
Headings structure content for both readers and search engines—use them to improve readability and SEO by including concise, descriptive phrases.
## Blockquotes
Use the greater-than symbol (`>`) to make quoted blocks:
```markdown theme={null}
> This is a quoted block. It will be indented and usually has a vertical line on the left.
```
Blockquotes are great for highlighting notes, quotes, or important callouts inside regular text.
## Emphasis and inline code
Use emphasis and inline code to call out terms, filenames, or commands:
* Italic: `*italic*` or `_italic_`
* Bold: `**bold**` or `__bold__`
* Inline code: use backticks `` `like this` ``
Example:
```markdown theme={null}
This is *italic* and this is **bold**. Use `inline code` for commands or filenames.
```
Tip: prefer inline code for short commands, filenames, or placeholders.
## Horizontal rule / divider
Separate sections with a horizontal rule. Any of these work:
```markdown theme={null}
---
***
___
```
Horizontal rules visually break longer README files into logical parts.
## Lists
Use unordered (bulleted) or ordered (numbered) lists for steps, features, or itemized details.
Unordered:
```markdown theme={null}
- Item A
- Item B
```
Ordered:
```markdown theme={null}
1. First item
2. Second item
```
Lists improve scanability and accessibility of README content.
## Task lists (checkboxes)
GitHub-Flavored Markdown supports task lists to show progress or checklist items:
```markdown theme={null}
- [x] Master HTML5, CSS & responsive design
- [x] Learn vanilla JavaScript
- [ ] Build and deploy a personal portfolio website
- [ ] Master Git and GitHub workflows
```
Task lists render as interactive checkboxes on GitHub and are useful for contributing guides or project roadmaps.
## Tables
Create tables with pipes (`|`) and separate the header row with dashes (`-`). Example:
```markdown theme={null}
| Category | Tools / Technologies |
| --- | --- |
| Frontend | HTML, CSS, JavaScript |
| Backend | Node.js, Express |
| Database | MongoDB, PostgreSQL |
| Tools | Git, VS Code, Figma |
| OS | Ubuntu, Windows |
```
Tables are ideal for comparing tools, listing features, or showing compatibility. Keep table rows concise for best readability.
## Links and featured projects
Create hyperlinks using square brackets for text and parentheses for the URL. Combine links with inline code formatting when you want to highlight technologies:
```markdown theme={null}
1. [My profile website](https://example.com)
2. [Project Repository](https://github.com/username/repo) — built with `HTML5`, `CSS`, `JavaScript`
```
These appear as clickable items in the rendered README.
***
Once you add these elements to your README and commit the changes (for example, committing directly to the `main` branch), GitHub will render headings, blockquotes, lists, task checkboxes, tables, and links—making your profile or project README easier to scan and more informative.
## Links and References
* [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/)
* [GitHub README rendering](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)
* [Markdown Guide](https://www.markdownguide.org/)
* [MDX documentation](https://mdxjs.com/)
Use these references for advanced MDX/Markdown features and best practices.