# Notion Formatting Guide: Visual Elements & Best Practices **Last Updated:** 2025-12-02 **Purpose:** Reference guide for all Notion-specific formatting, syntax, and visual elements used in the 2026 strategy documents --- ## Overview This guide documents all Notion formatting capabilities used to enhance the MAIN_PLAN.md document. Notion supports rich markdown formatting with additional visual elements like callouts, toggles, code blocks, and Mermaid diagrams. --- ## 1. Callout Blocks Callout blocks are highlighted sections that draw attention to important information. They use the `> ` prefix followed by an emoji and text. ### Syntax ```markdown > 💡 **Tip Title** > > Callout content here... ``` ### Common Callout Types | Emoji | Type | Use Case | Example | | ----- | --------- | ----------------------------------- | --------------------------------------- | | 💡 | Info/Tip | Helpful information, best practices | "💡 **Tip:** Start with MVP..." | | ⚠️ | Warning | Risks, cautions, important warnings | "⚠️ **Warning:** This may disrupt..." | | ✅ | Success | Achievements, completed items | "✅ **Completed:** Template system..." | | 📊 | Data | Metrics, statistics, insights | "📊 **Key Metric:** 17,915 sessions..." | | 🎯 | Goal | Objectives, targets, KPIs | "🎯 **Target:** 50,000 sessions..." | | ❓ | Question | Questions, considerations | "❓ **Question:** Should we...?" | | 🔥 | Important | Critical information | "🔥 **Critical:** This requires..." | | 💭 | Note | Additional context, notes | "💭 **Note:** This assumes..." | ### Best Practices - Use callouts sparingly for maximum impact - Keep callout content concise (1-3 sentences) - Use appropriate emoji that matches the content type - Bold the title for better visual hierarchy --- ## 2. Toggle Lists (Collapsible Sections) Toggle lists allow content to be collapsed/expanded, making documents cleaner and more scannable. ### Syntax ```markdown - Toggle Title - Content inside toggle - Can have multiple items - Supports nested formatting ``` ### When to Use - Technical details that not everyone needs - Implementation specifics - Background context - Additional resources - Detailed explanations that can be skipped ### Example ```markdown - Technical Implementation Details - Template generator uses PHPExcel library - Competitor data stored in JSON format - Monthly scraping via Python cron job ``` --- ## 3. Mermaid Diagrams Notion supports Mermaid diagrams through code blocks. Mermaid is a diagramming and charting tool that uses text-based syntax. ### Syntax ````markdown ```mermaid graph TD A[Start] --> B[Process] B --> C[End] ``` ```` ### Supported Diagram Types 1. **Flowcharts:** Process flows, decision trees 2. **Sequence Diagrams:** Interactions, workflows 3. **Gantt Charts:** Timelines, schedules 4. **Timeline Diagrams:** Chronological events 5. **Class Diagrams:** Architecture, relationships 6. **State Diagrams:** State transitions ### Best Practices - Keep diagrams simple and focused - Use descriptive labels - Test diagrams render correctly - Provide text alternative if diagram is complex --- ## 4. Code Blocks Code blocks with syntax highlighting for technical examples. ### Syntax ````markdown ```language code here ``` ```` ### Supported Languages - `javascript`, `python`, `php`, `json`, `yaml`, `sql`, `bash`, etc. - `mermaid` for diagrams ### When to Use - API examples - Configuration snippets - Data structures - Code examples - Formulas --- ## 5. Tables Notion supports rich table formatting with alignment, headers, and merged cells. ### Syntax ```markdown | Column 1 | Column 2 | Column 3 | | -------- | -------- | -------- | | Data 1 | Data 2 | Data 3 | ``` ### Enhancement Tips - Use bold headers for clarity - Align numeric data to the right - Use consistent spacing - Add callouts within tables for notes --- ## 6. Headers & Hierarchy Notion supports 6 levels of headers (H1-H6). ### Syntax ```markdown # H1 (Page Title) ## H2 (Major Section) ### H3 (Subsection) #### H4 (Sub-subsection) ##### H5 (Minor heading) ###### H6 (Smallest heading) ``` ### Best Practices - Use H2 for major sections - Use H3 for subsections - Limit to 3-4 levels for readability - Maintain consistent hierarchy --- ## 7. Lists Notion supports ordered, unordered, and nested lists. ### Unordered Lists ```markdown - Item 1 - Item 2 - Nested item - Another nested item - Item 3 ``` ### Ordered Lists ```markdown 1. First item 2. Second item 1. Nested item 2. Another nested item 3. Third item ``` ### Task Lists (Checkboxes) ```markdown - [ ] Incomplete task - [x] Completed task ``` --- ## 8. Text Formatting ### Bold ```markdown **bold text** ``` ### Italic ```markdown _italic text_ ``` ### Bold + Italic ```markdown **_bold and italic_** ``` ### Inline Code ```markdown `code snippet` ``` ### Strikethrough ```markdown ~~strikethrough text~~ ``` ### Highlight Notion supports highlights through UI, but markdown uses: ```markdown ==highlighted text== ``` --- ## 9. Links ### External Links ```markdown [Link Text](https://example.com) ``` ### Internal Links (Notion Pages) In Notion, internal links are created via UI. In markdown, use: ```markdown [Page Name](page-url) ``` ### Anchor Links (Same Page) ```markdown [Section Name](#section-name) ``` --- ## 10. Dividers Horizontal dividers to separate sections. ### Syntax ```markdown --- ``` --- ## 11. Block Quotes For quotes or emphasis. ### Syntax ```markdown > Quote text here ``` --- ## 12. Images ### Syntax ```markdown ![Alt text](image-url) ``` --- ## Visual Hierarchy Best Practices ### 1. Use Callouts Strategically - Don't overuse callouts (max 1-2 per major section) - Choose appropriate emoji types - Keep content concise ### 2. Organize with Toggles - Collapse detailed technical information - Make documents more scannable - Keep important info visible ### 3. Enhance Tables - Bold headers - Use consistent formatting - Add notes via callouts within tables ### 4. Diagram Guidelines - Keep diagrams simple - Use descriptive labels - Test rendering - Provide context ### 5. Consistent Formatting - Standardize heading levels - Use consistent list styles - Maintain spacing --- ## Notion-Specific Features ### 1. Databases Notion supports database views (table, board, timeline, calendar, gallery). In markdown, these are represented as tables or lists. ### 2. Relations & Rollups Advanced database features require Notion UI setup, not markdown. ### 3. Formulas Database formulas require Notion UI setup. ### 4. Templates Notion page templates require UI setup. --- ## Common Patterns for Strategy Documents ### Pattern 1: Metric Highlight ```markdown > 📊 **Key Metric** > > Monthly Organic Sessions: **17,915** (Nov 2025) > Target: **50,000-75,000** (Dec 2026) ``` ### Pattern 2: Risk Warning ```markdown > ⚠️ **Risk Warning** > > Blog migration may cause temporary traffic disruption. Mitigation: Phased approach with 301 redirects. ``` ### Pattern 3: Collapsed Details ```markdown - Technical Implementation - Uses PHPExcel library - JSON data format - Python cron for automation ``` ### Pattern 4: Process Flow ````markdown ```mermaid flowchart TD A[Input] --> B[Process] B --> C[Output] ``` ```` --- ## References - [Notion Formatting Guide](https://www.notion.so/help/format-your-content) - [Mermaid Documentation](https://mermaid.js.org/) - [Notion Best Practices](https://www.notion.so/help/category/best-practices) --- ## Next Steps 1. Apply these patterns to MAIN_PLAN.md 2. Test all visual elements render correctly 3. Ensure consistent formatting throughout 4. Validate diagrams and code blocks