Vellum: A Simple Documentation Template

Showcase
1

Hola everyone!

I’m excited to share Vellum, a new documentation template I’ve been building over the last month. My goal was to create something powerful for developers but still simple enough for non-technical writers, all while keeping Markdown at the core of the experience.

I’d love to get your feedback on any bad practices I might have missed or any ideas for improvement.

Links:

Key Features

  • Markdown is all you need: Write content and even complex components using familiar Markdown syntax.
  • Visually edit with CloudCannon: Non-technical users can build pages visually using Bookshop components.
  • Full Theming Control:
    • Easily define your own light and dark mode color palettes.
    • Choose any font from Google Fonts for headings, body text, and your logo.
    • Upload light and dark theme logos
  • “Collection” Based Routing: The navigation bar intelligently shows only the docs relevant to the selected collection, keeping things tidy.
  • Advanced Authoring Components:
    • Tabs
    • Accordions
    • Mermaid.js graphs
    • Task lists
    • Callouts (info, warning, error)
    • Label text styling (green, orange, red, blue, kbd{this one is styled like a keyboard key})
    • All components are nestable, in raw markdown and through bookshop.
  • Robust & SEO-Friendly:
    • Duplicate permalink checker to prevent build failures.
    • Dynamic permalinks for clean URLs (folder becomes part of url).
    • Automatic sitemap.xml and robots.txt generation.
    • Automatic image optimization, you don’t have to do anything (11ty img)
  • Flexible & Powerful:
    • Site-wide banner for announcements.
    • Custom code injection (site-wide or per-page) for analytics and tracking scripts or anything else.
    • Draft page functionality so you can publish when ready.
    • Nested navigation powered by 11ty Navigation.
    • Responsive tables using <table-saw>.

Known shortcomings

I still need to write documentation on how to use Vellum without connecting to Cloucannon, but since it is Cloudcannon ready, I thought I’d share this early to get some feedback.

But why another documentation template?

Curious about the origin story? Here’s the why behind Vellum.

Before creating Vellum, I explored existing documentation frameworks. I found that many popular options felt overly complex for my needs, often requiring React and a steep learning curve. They are powerful, but they’re built to support a huge variety of use cases. This led me to ask a few questions.

What if there was something easier to set up and learn?

Vellum is designed to be as intuitive as possible. There are only four “config” files that handle basic site and theme setup. My goal was to create an experience where both developers and non-technical editors could feel comfortable and productive right away.

What if a template could be used by developers AND non-technical editors?

Many of us love writing in Markdown, but not everyone wants to learn it. To bridge this gap, I created parity between what a developer can write in Markdown and what a non-technical editor can create visually in CloudCannon. Using Bookshop components, editors can build pages and see their changes in real-time, no Markdown knowledge required.

What if complex components could still be written in Markdown?

My own documentation is a mix of handwritten, programmatically generated, and AI assisted content, all of it is based in Markdown. I wanted to extend this simplicity to more complex UI elements.

Through a combination of markdown-it plugins, some CSS, and a bit of JS, Vellum supports components like tabs, accordions, and Mermaid graphs directly in your Markdown files. This allows for a rich authoring experience without ever leaving your favorite text editor, or having to write inline html.

By answering these questions, Vellum was born. It’s my take on a documentation template that’s simple, flexible, and accessible to everyone.

7 Likes