Floating [TOC] sidebar using custom CSS

[erkamakbas]

Floating [TOC] sidebar using custom CSS

MarkdownPreview already supports Python-Markdown's TOC extension, so a Markdown file can include:

# My Document

[TOC]

## Introduction
## Methods
## Results

By default, this creates an inline table of contents. For long technical documents, I wanted a right-side floating outline/sidebar similar to documentation sites.

This can be done without changing MarkdownPreview itself by using the existing custom CSS support.

MarkdownPreview setting

In MarkdownPreview.sublime-settings:

{
    "parser": "markdown",
    "css": {
        "markdown": [
            "default",
            "C:/path/to/markdownpreview-floating-toc.css"
        ]
    }
}

Example CSS

/* GitHub-like floating TOC for MarkdownPreview */

body {
    max-width: 900px;
    margin-left: 3rem;
    margin-right: 22rem;
}

/* GitHub light theme defaults */
.toc {
    position: fixed;
    top: 4rem;
    right: 1.5rem;
    width: 18rem;
    max-height: 80vh;
    overflow-y: auto;

    padding: 1rem;
    border: 1px solid #d0d7de;
    border-radius: 6px;

    background: #ffffff;
    color: #24292f;

    font-size: 0.9rem;
    line-height: 1.35;
    box-shadow: 0 8px 24px rgba(140, 149, 159, 0.2);
    z-index: 1000;
}

.toc::before {
    content: "Table of contents";
    display: block;
    margin-bottom: 0.5rem;
    font-weight: 600;
    color: #24292f;
}

.toc ul {
    padding-left: 1.1rem;
    margin: 0.25rem 0;
}

.toc li {
    margin: 0.25rem 0;
}

.toc a {
    color: #0969da;
    text-decoration: none;
}

.toc a:hover {
    text-decoration: underline;
}

/* GitHub dark theme */
@media (prefers-color-scheme: dark) {
    .toc {
        border-color: #30363d;
        background: #0d1117;
        color: #c9d1d9;
        box-shadow: 0 8px 24px rgba(1, 4, 9, 0.8);
    }

    .toc::before {
        color: #c9d1d9;
    }

    .toc a {
        color: #58a6ff;
    }
}

/* MarkdownPreview may also set body data-theme */
body[data-theme="dark"] .toc {
    border-color: #30363d;
    background: #0d1117;
    color: #c9d1d9;
    box-shadow: 0 8px 24px rgba(1, 4, 9, 0.8);
}

body[data-theme="dark"] .toc::before {
    color: #c9d1d9;
}

body[data-theme="dark"] .toc a {
    color: #58a6ff;
}

body[data-theme="light"] .toc {
    border-color: #d0d7de;
    background: #ffffff;
    color: #24292f;
    box-shadow: 0 8px 24px rgba(140, 149, 159, 0.2);
}

body[data-theme="light"] .toc::before {
    color: #24292f;
}

body[data-theme="light"] .toc a {
    color: #0969da;
}

/* Narrow screens: make TOC inline again */
@media screen and (max-width: 1100px) {
    body {
        margin-right: 3rem;
    }

    .toc {
        position: static;
        width: auto;
        max-height: none;
        box-shadow: none;
        margin: 1rem 0;
    }
}

Notes

• This targets the .toc element generated by Python-Markdown's markdown.extensions.toc.
• Uses existing supported settings: css, allow_css_overrides, and [TOC].
• No need to change MarkdownPreview's parser behavior.
• Helps users navigate long Markdown documents. Particularly useful for academic/technical Markdown documents with many headings.
• On narrow screens, the TOC returns to normal document flow.

Suggestions or improvements are welcome.