# Custom Formatting Guide for Obsidian Publish This guide explains how to use custom heading styles and collapsible sections in your Obsidian notes that will display properly on your published website. ## Table of Contents - [Custom Heading Styles](#custom-heading-styles) - [Collapsible Sections](#collapsible-sections) - [Excluding Headings from TOC](#excluding-headings-from-toc) - [Performance Notes](#performance-notes) --- ## Custom Heading Styles All custom headings use **real HTML heading tags with CSS classes**. They automatically appear in your TOC with proper hierarchy. ### 1. Alternative Compact Heading **Use for:** Sub-points, technical details, or supplementary sections that need less visual weight **Syntax:** ```html <h2 class="alt-heading">Your Text Here</h2> <h3 class="alt-heading">Your Text Here</h3> <h4 class="alt-heading">Your Text Here</h4> ``` **Styling:** Blue color, smaller font (1em), tight spacing, left border accent **Example:** ```html ## Normal Heading <h3 class="alt-heading">Related Technical Detail</h3> Some content here... ``` --- ### 2. Appendix/Footnote Heading **Use for:** Appendix sections, footnotes, references, or end-of-document material **Syntax:** ```html <h2 class="appendix-heading">Appendix</h2> <h3 class="appendix-heading">Footnotes</h3> ``` **Styling:** Gray color, uppercase, top border, extra spacing above **Example:** ```html Your main content... <h2 class="appendix-heading">Appendix: Additional Data</h2> Supplementary information... ``` --- ### 3. Muted/Subtle Heading **Use for:** Optional reading, tangential information, or less critical sections **Syntax:** ```html <h3 class="muted-heading">Optional Context</h3> <h4 class="muted-heading">Historical Note</h4> ``` **Styling:** Gray italic text, smaller font, minimal spacing **Example:** ```html ## Main Finding <h4 class="muted-heading">Historical Background (Optional)</h4> This approach was first proposed in... ``` --- ### 4. Highlight Heading **Use for:** Important findings, key takeaways, critical sections **Syntax:** ```html <h2 class="highlight-heading">Key Finding</h2> <h3 class="highlight-heading">Important Note</h3> ``` **Styling:** Bold text, yellow background highlight, slightly larger **Example:** ```html <h2 class="highlight-heading">Critical Safety Information</h2> This pathway is essential for... ``` --- ## Collapsible Sections Use native HTML `<details>` and `<summary>` tags for progressive disclosure. These do NOT appear in the TOC. ### 1. General Information Collapse **Use for:** Additional context, explanations, or supplementary data **Syntax:** ```html <details class="info-collapse"> <summary>Click to expand: Additional Details</summary> Your content here. Can include: - Lists - **Bold text** - Multiple paragraphs </details> ``` **Behavior:** Collapsed by default, light background --- ### 2. Data/Evidence Collapse **Use for:** Research data, study details, technical evidence **Syntax:** ```html <details class="data-collapse"> <summary>Study Data</summary> - Study participants: 150 - Duration: 6 months - Key findings: ... </details> ``` **Styling:** Blue accent, lighter background --- ### 3. Appendix Collapse **Use for:** Collapsible appendix sections with lots of content **Syntax:** ```html <details class="appendix-collapse"> <summary>Appendix A: Supplementary Methods</summary> Your appendix content here... </details> ``` **Styling:** Top border, uppercase summary, full width --- ### Making Collapsible Sections Open by Default Add the `open` attribute: ```html <details class="info-collapse" open> <summary>This starts expanded</summary> Content... </details> ``` --- ## Excluding Headings from TOC To create a heading that appears in your document but NOT in the TOC, add the `no-toc` class: **Syntax:** ```html <h2 class="no-toc">This Won't Appear in TOC</h2> <h3 class="no-toc appendix-heading">Hidden Appendix</h3> ``` **You can combine classes:** ```html <h3 class="alt-heading no-toc">Hidden Alt Heading</h3> ``` --- ## Complete Example Here's how to structure a complex document: ```markdown # Main Document Title ## Introduction Regular markdown content... <h3 class="alt-heading">Technical Background</h3> More specific technical details... ## Key Findings <h2 class="highlight-heading">Critical Discovery</h2> This is important! <details class="data-collapse"> <summary>Supporting Data</summary> - Experiment 1: ... - Experiment 2: ... </details> <h4 class="muted-heading">Historical Context</h4> Optional reading material... ## Conclusion Summary of findings... <h2 class="appendix-heading no-toc">Appendix</h2> This heading won't appear in TOC but will display in the document. <details class="appendix-collapse"> <summary>Supplementary Methods</summary> Detailed methodology... </details> ``` --- ## Performance Notes **Load Time Impact:** Minimal - CSS classes add negligible overhead - A few extra classes won't slow down your site - JavaScript only runs once on page load - Collapsible sections use native HTML (very efficient) **Scalability:** - These styles work efficiently across hundreds of notes - No database queries or server-side processing - All styling happens in the browser **Best Practices:** - Use custom headings purposefully, not excessively - Maintain clear hierarchy (don't skip heading levels) - Use collapsible sections for truly supplementary content - Test on mobile to ensure readability --- ## Customizing Colors and Styling All styling is in your `publish.css` file under the "CUSTOM HEADING STYLES" section. To change colors: 1. Find the heading class in publish.css 2. Modify the `color:` or `background-color:` values 3. Use your existing CSS variables for consistency: - `var(--link-color)` - your blue links - `var(--text-muted)` - gray text - `var(--border-color)` - borders - `var(--background-secondary)` - light backgrounds --- ## Tips for Scientific Wiki **For Progressive Disclosure:** 1. Main narrative in regular headings 2. Supporting evidence in collapsible sections 3. Technical details in alt-headings 4. Optional context in muted headings **Hierarchy Example:** ``` # Main Topic (H1 - page title) ## Core Concept (H2 - main sections) ### Detailed Mechanism (H3 - subsections) <h4 class="alt-heading">Technical Note</h4> <details>Evidence</details> <h4 class="muted-heading">Optional Context</h4> ``` This approach keeps your content scannable while providing depth for those who want it!