Context Vigilance
Search/

← Corpus / astro-knots / prompt

astro-knots

astro-knots/prompts/discuss-how-to-publish-long-form-like-ebook

Path
prompts/Discuss-how-to-Publish-Long-Form-like-eBook.md

Context

We have an old ebook that was a Google Doc, I drove it and wrote most of it but a lot of the content came from my classmates.

I’ve put it in markdown and HTML download form here:

[!LOUD-TITLE] Perspectives & Practice (Voodoo Handbook) Class 20 Living Draft

  • /Users/mpstaton/code/lossless-monorepo/astro-knots/context-v/extra/background-content

I’m asking Claude Code on Opus 4.7 to help me figure out the best way to publish this as a long-form piece like an ebook. This is a next-logical-task after pulling the Grid Card layout content from the section headers from the long form report.

The Lossless Reader

On the Lossless Group website, we have a “Reader” that has clever functionality.

However, it’s a bit much, custom, and likely visually distracting for a long-form piece like an ebook.

Astro Starlight

Astro also has Starlight, which is a pre-built documentation engine. I’m not sure I want to rely on their package and keep that updated, and deal with styling conflicts. Or even figure out how they reason about long form, complex content.

MDBook

https://rust-lang.github.io/mdBook/

If I’m going to have to reason about someone elses code, I’d rather ALSO use it as a way to get familiar with Rust, as there are projects I want to do in Rust.

Just Wing It

Maybe I should let Claude Code on Opus 4.7 just wing it.

If so, it DOES, need to use Lossless Flavored Markdown, which still has a number of features we need to add and trying to get it done will force us to work through some of the smaller wish list of features.

Claude’s Discussion (2026-04-26, Opus 4.7)

Put together from web search + reading the source manuscript + reading the existing Lossless Reader code at /Users/mpstaton/code/lossless-monorepo/site/src/pages/read/. References inline.

What we’re actually shipping

Before evaluating tools, the shape of the artifact matters. Looking at the source — Perspectives & Practice (Voodoo Handbook) Class 20 Living Draft.md (1,751 lines):

  • 10 numbered chapters (“Areas of Venture”) plus a “New Models of Venture Capital” intro and a “Perspectives” appendix.
  • Repeating sub-section grammar per chapter: Discussion → Foundations / Tradecraft → Tips & Tricks → Tools of the Trade → Case Studies → Highlights.
  • ~50 numbered footnotes ([^1]-style) — LFM citations already handles this.
  • ~25+ embedded images (Google Doc download style: ![][image1], with the binary assets sitting in the .zip next to the markdown). These need to be extracted and re-keyed.
  • Several markdown tables (valuation methods table, etc.) — GFM territory, already in LFM.
  • A handful of inline links to source articles (mostly TechCrunch-era 2016).
  • Voice/tone: a real piece of writing with first-person passages — this is editorial, not a docs site. The chrome around it should disappear.

That last point is the one that drives the call. This isn’t documentation. It’s a book. So the question isn’t “which docs framework wins” — it’s “how do we render a long-form editorial artifact while reusing as much of the FullStack VC stack as possible.”

Option-by-option

1. The Lossless Reader (/read/through)

What it is — an Astro content-collection-driven reader at site/src/pages/read/through/[collection]/[...slug].astro, fronted by CollectionReaderLayout. Each essay is one file in the essays collection.

Pros

  • It’s yours. Zero new dependency, zero theming fight.
  • Already integrates with your essay collection model.
  • Already handles published/unpublished filtering.

Cons (the ones you flagged, plus a few)

  • Built for standalone essays, not for a single bound book with sequential chapters. There’s no native chapter-prev/next, no global TOC, no chapter numbering.
  • It lives in a different repo (lossless-monorepo/site) — porting that reader into FullStack VC means either copying the layout (the @knots-style copy-and-adapt motion), or re-pointing the book at lossless.group/read/through/venture-handbook/..., which fragments the FullStack VC brand experience.
  • “A bit much, custom, and likely visually distracting” — your own assessment, and it’s right. Side panels and clever interactions actively work against the immersion a long read needs.

Verdict — Wrong shape for the artifact. Skip.

2. Astro Starlight

What it is — Astro’s first-party docs framework. Mature, accessible, ships with sidebar nav, search, prev/next, mobile TOC out of the box. Now on a stable cadence after Astro 6’s release (Astro 6 docs, Starlight docs).

Pros

  • The chapter-navigation primitives you’d otherwise hand-roll (sidebar with chapter ordering, in-page TOC, prev/next at the bottom of every page) come free.
  • Active maintenance, big surface area of community plugins, search baked in.
  • Astro-native — same SSR model, deploys to Vercel like the rest of the site.

Cons in this context

  • Theming fight. Starlight has a strong opinionated visual identity (sidebar-left, content-center, TOC-right). To make it look like the FullStack VC dojo brand — your two-tier --color-*/--color__* token system, your three-mode toggle (light/dark/vibrant), your display font usage — you’d be overriding their CSS variables and component slots, which works but means you’re tracking their internal naming as a stable surface.
  • It’s a docs framework — the visual default speaks “API reference,” not “ebook.” Even with theming, the muscle memory of the framework pulls you toward docs aesthetics.
  • Mounted as a sub-app. Starlight wants to own a route subtree, not be embedded as one section of your app. Practically: you’d run it under /read/venture-handbook/... with its own layout chain, breaking from BaseThemeLayout. That’s not the end of the world but it adds drift between the “rest of the site” and “the book.”
  • LFM compatibility unknown. Starlight processes markdown through its own remark/rehype pipeline; you’d need to wire @lossless-group/lfm plugins into Starlight’s config (doable, but another integration to maintain).

Verdict — Strong on chapter chrome, weak on aesthetic fit. The theming overhead is real, and it’s not the kind of bug-fixing fun you actually want to spend time on.

3. mdBook

What it is — Rust-based static-site generator that reads a SUMMARY.md and outputs a hyperlinked book (rust-lang/mdBook). Used by the Rust language’s own books.

Pros

  • Excellent at exactly this shape of content: numbered chapters, sequential reading, prev/next, search.
  • Tiny output, no JS runtime to speak of.
  • Genuinely good way to learn Rust idioms if you go reading the source — you mentioned this is part of the appeal.

Cons in this context

  • Standalone artifact. mdBook outputs its own static site with its own theme system (Handlebars + CSS). To make it visually match FullStack VC’s dojo, you’re either rewriting their theme (Rust + Handlebars work, not Astro work) or accepting that the book lives at a sub-domain or sub-path that looks different from the rest of the site.
  • Markdown dialect mismatch. mdBook uses CommonMark + a small set of extensions. None of your LFM features (citations, callouts as directives, future wikilinks/transclusions) exist there. You’d be giving up the shared pipeline you just published and having to rewrite content if it ever moves.
  • Two-language stack. You’d be context-switching between Rust (book theme/build) and TypeScript/Astro (the rest of the site) for every change.
  • Rust-learning ROI is real but indirect. If you want a Rust project, picking an actual Rust project is more efficient than learning Rust through a templating layer.

Verdict — Tempting for the Rust-learning angle but bad for product cohesion. Save the Rust appetite for a project where Rust is load-bearing.

What it is — Render the book as an Astro content collection inside sites/fullstack-vc, processed by @lossless-group/lfm, with a purpose-built BookReaderLayout that reads from BaseThemeLayout and uses your existing semantic tokens.

Why this wins for this artifact

  • Brand cohesion. Same theme/mode toggle, same fonts, same surface tokens as /dojo. The book is the FullStack VC dojo’s library, not an annex.
  • You already own the pipeline. LFM handles GFM, directives, callouts, and citations. Footnotes work the day you import it. Tables work. The ~50 footnotes in the source render correctly without writing a line of plugin code.
  • Forces the LFM wishlist forward. The features missing from LFM today — wikilinks, transclusions, image directives with caption/credit, heading-slug-based anchors — are exactly what a serious longform piece needs. Building them here puts them in the published @lossless-group/lfm package, which makes mpstaton-site, twf-site, etc. better in the same motion. That compounds.
  • Cheap chapter chrome. Prev/next, TOC, and chapter numbering are 50–100 lines of Astro on top of a content collection. It’s not a project; it’s an afternoon. (Astro prev/next pattern)

What you’d build (concrete, in priority order)

  1. A book content collection under src/content/books/venture-handbook/ with one file per chapter (00-intro.md, 01-strategy-and-raising.md, …, 10-exits.md, 99-perspectives.md). Frontmatter: chapterNumber, title, subtitle?, published.
  2. A BookReaderLayout.astro that wraps BaseThemeLayout with: max-width prose column (~70ch), generous line-height, larger body type, in-content footnote rendering via Sources.astro (already a copy-pattern from packages/lfm-astro/components/), prev/next at bottom, breadcrumb at top.
  3. AstroMarkdown.astro copied from packages/lfm-astro/components/ and adapted — same recursive MDAST renderer used elsewhere.
  4. A book index page at /library/venture-handbook/ showing the chapter list (you already have the chapter data — it’s the same array we just used for AreasOfVentureGrid on /dojo, modulo the intro/appendix entries).
  5. Image handling. Unzip the assets bundle, drop them in public/library/venture-handbook/, and write a one-time content-fixup script to rewrite ![][imageN] references to real paths. (This is also a forcing function for an LFM image directive — :::image{src=… caption=… credit=…} — that mpstaton-site has been wanting too.)
  6. Optional, later: dynamic sub-section navigation per chapter (Discussion / Tips & Tricks / Case Studies / Highlights as anchor jumps in the chapter sidebar), reading-progress bar, “save my place” via localStorage.

LFM features this would push forward (the “wishlist as a forcing function” part)

  • remark-image-directive — :::image{...} with caption/credit/alt/figure-vs-inline.
  • remark-heading-slugs + remark-toc — for stable anchors and per-chapter TOCs.
  • remark-wikilinks — [[Other Chapter#Section]] cross-chapter linking.
  • rehype-shiki integration — even if there’s no code in this book, every other long-form thing you’ll ever publish will want it.
  • A first-class @lossless-group/lfm-astro package promotion — right now packages/lfm-astro/components/ is a copy-source. If we build the book reader with it, it earns enough usage signal to publish properly.

Cons (the honest ones)

  • It’s still bespoke work. None of it is hard, but it’s all on you/Claude. Two days of focused work, not an evening.
  • You’re now responsible for chapter-navigation correctness instead of inheriting it from a framework. Cheap to write, cheap to break.

5. Bonus option I’d add: Quartz 4

Worth naming because it kept showing up in adjacent searches (Quartz 4). Quartz is purpose-built for publishing Obsidian vaults — wikilinks, transclusions, backlinks, graph view, all native. If the corpus you wanted to publish were your Obsidian notes as a digital garden, Quartz would be the right call.

It’s the wrong call here for the same reason mdBook is: it’s a separate app with its own theme system, and the Venture Handbook is a bound book, not a graph of notes. But park this one for whenever you decide to publish the rest of context-v as a public garden.

Recommendation

Wing it with LFM. Specifically:

  • Ship the book as a content collection inside sites/fullstack-vc under /library/venture-handbook/, rendered by a small BookReaderLayout over BaseThemeLayout.
  • Use the work to push three concrete features into @lossless-group/lfm: image directive, heading slugs + per-chapter TOC, and a first cut at wikilinks.
  • Leave Starlight, mdBook, Quartz on the shelf. They’re each great tools for the project they’re built for, and this isn’t that project.

The Rust itch is real but should be scratched somewhere it actually compounds — a CLI, a markdown linter, a build tool — not a templating layer for one book.

What I’d want you to push back on

  1. /library/ vs /read/ vs /dojo/library/ — naming the route. I picked /library/venture-handbook/ because it implies a shelf for future books. You may have a stronger view.
  2. Whether the chapters get rewritten/edited or shipped as-is. The 2016-era references read as historical now; do you want light editorial passes per chapter, or “living draft” honesty preserved with a date header?
  3. Image handling effort. Unzipping and re-keying ~25 images is a one-time chore. Worth doing properly (with an LFM image directive) vs. quick-and-dirty (raw <img> tags) — I’d vote properly, but it’s two extra hours.
  4. Whether the book becomes part of /dojo navigation or its own top-level nav item. Probably the latter, but worth deciding before we ship.

Sources: