Skip to main content

MAC Docusaurus

PropertyValue
descriptionMAC Docusaurus
tagsindex, doc, mac-docusaurus

Overview​

MAC Docusaurus is the active local Docusaurus package that powers the MAC Docs site theme and the site-side compatibility layer for this vault.

It is the part of the stack that is real, working, and currently in daily use.

What It Owns​

MAC Docusaurus is not just a stylesheet.

It currently owns:

  • the site-wide MAC visual theme
  • the MAC Prism theme
  • bundled MAC fonts and icons
  • bundled mac-* site assets such as logos, favicons, and background images
  • Obsidian callout parsing for the site
  • Obsidian ==highlight== parsing for the site
  • local PDF embed support for the site
  • local ZIP download embed support for the site
  • local code-file embed support for the site
  • local .base embed support for the site
  • normal Markdown table wrapping with horizontal overflow handling
  • table copy-as-Markdown controls for both normal tables and base tables
  • the MacCallout, MacPdfEmbed, MacDownloadEmbed, MacBaseTable, and MacMarkdownTable MDX components
  • DocSearch and Ask AI styling

What It Changes On The Site​

The plugin is responsible for the active MAC visual language across the site, including:

  • page surfaces and shell styling
  • callouts and admonitions
  • code blocks and embedded code files
  • embedded PDFs
  • embedded ZIP download buttons
  • Obsidian base embeds rendered as website tables
  • normal Markdown tables rendered through a shared overflow wrapper
  • typography tokens
  • inline code and kbd
  • copy controls for table surfaces
  • tables and details/summary
  • DocSearch and Ask AI styling

It also adds build-time transforms so the Obsidian vault files can stay canonical while the published site still renders richer output.

How It Fits With The Obsidian Side​

Right now the Docusaurus side is ahead of the Obsidian side.

Current reality:

So MAC Docusaurus is currently the mature part of the broader MAC Docs toolchain.

Key Files​

If you want to understand or reuse the current setup, these are the key files:

  • plugins/mac-docusaurus/index.ts
  • plugins/mac-docusaurus/styles.css
  • plugins/mac-docusaurus/theme/MDXComponents.tsx
  • plugins/mac-docusaurus/theme/MacCallout/index.tsx
  • plugins/mac-docusaurus/theme/MacBaseTable/index.tsx
  • plugins/mac-docusaurus/theme/MacBaseTable/TableCopyButton.tsx
  • plugins/mac-docusaurus/theme/MacMarkdownTable/index.tsx
  • plugins/mac-docusaurus/theme/MacPdfEmbed/index.tsx
  • plugins/mac-docusaurus/theme/MacDownloadEmbed/index.tsx
  • plugins/mac-docusaurus/assets/fonts/
  • plugins/mac-docusaurus/assets/icons/
  • plugins/mac-docusaurus/static/
  • docusaurus.config.ts
  • src/theme/MDXComponents.tsx

What It Does Today​

The main site-side markdown compatibility features currently in use are:

  • Obsidian callouts rendered as custom site callouts
  • Obsidian ==highlight== rendered properly on the site
  • local code-file embeds rendered as real code blocks on the site
  • local Obsidian-style PDF embeds rendered as embedded PDFs on the site with action labels driven by the Markdown alt text
  • local Obsidian-style ZIP embeds rendered as download buttons on the site with labels driven by the Markdown alt text
  • local .base embeds rendered as read-only website tables with row collapsing and copy support
  • normal Markdown tables rendered through a dedicated wrapper so wide tables scroll instead of overflowing
  • normal Markdown tables exposed through the same table copy affordance used by base tables

Those transforms are intentionally narrow and allowlisted. The goal is to support the vault safely, not to add a giant loose markdown compatibility layer.

For file-style embeds, the current authoring rule is simple:

  • use the Markdown alt text as the visible label when present
  • fall back to the filename when the alt text is empty
  • if code-file embeds gain a visible block title in the future, that title should follow the same alt-text rule

Table Rendering Model​

There are currently two table paths on the site:

  • normal Markdown tables render through MacMarkdownTable
  • Obsidian .base embeds render through MacBaseTable

That split is intentional.

Normal Markdown tables stay author-friendly in the vault, but the site wraps them in a shared scroll surface so wide tables do not break the layout.

Base embeds stay data-driven and compile into a richer read-only table view with:

  • column labels humanized from the order keys, whether they target file.* fields or arbitrary frontmatter properties
  • filtered and sorted repo-backed rows
  • boolean frontmatter values rendered as true/false icons instead of raw text
  • row collapsing after the default visible threshold
  • copy-as-Markdown support

Both table paths now expose the same copy button pattern on the site.

Base Notes​

The current site-side .base support is still intentionally narrow, but there are a few details that matter in practice:

  • file.name includes the extension, so folder landing-page tables should usually filter with file.name == "index.md"
  • order columns can target file.* fields and arbitrary frontmatter keys
  • boolean frontmatter values render as icons in MacBaseTable
  • the boolean icons are sourced from plugins/mac-docusaurus/assets/icons/ and are colored through CSS masks plus currentColor, not by hardcoded SVG paint values
  • custom icons in that folder should continue to use the Streamline Bold set as the default source

Reuse Notes​

MAC Docusaurus is reusable, but it is not yet a one-line install.

Another repo still needs:

  1. the local plugin copied into the repo
  2. explicit docusaurus.config.ts wiring
  3. docs remark plugin wiring
  4. Prism theme hookup
  5. the current root MDX shim
  6. plugin static asset exposure through staticDirectories

The preferred future packaging direction is still:

  • docusaurus-preset-mac

That would be the cleaner long-term packaging layer once this in-repo setup is extracted and stabilized.

Relationship To Other MAC Docs Products​

  • MAC Docusaurus is the site-side build, theme, and compatibility layer
  • MAC Obsidian Theme is the planned Obsidian-side visual layer
  • MAC Obsidian Plugin is the planned Obsidian-side behavior layer

The long-term goal is one canonical vault with:

  • Obsidian as the writing environment
  • Docusaurus as the publishing environment