Astro Knots
A pseudomonorepo for the age of AI-assisted development. Twelve Astro sites with dashes of Svelte, Reveal.js, and Tailwind v4 — co-located so patterns, context, and design conventions can travel between them without forcing premature abstraction.
- Slideshows & Scroll Decks
- Three Modes — Light, Dark, Vibrant
- Design Systems & Brand Kits
- Agent Skills
- Context Vigilance
- Lossless Flavored Markdown
Why a Pseudomonorepo?
Not a true monorepo. Not a loose collection of repos. A pseudomonorepo gives you the visibility and pattern-sharing benefits of co-location without coupling deployment or forcing shared dependencies where they don't belong.
Accelerate with Shared Patterns
Co-locate projects with similar features, dependencies, and needs. Abstract what works into reusable patterns -- extended markdown render pipelines, CSS token conventions, OpenGraph and SEO optimization techniques -- without forcing premature abstraction.
Context Vigilance
Maintain structured, AI-friendly documentation that travels with the workspace. Specs, blueprints, prompts, and reminders give both human collaborators and AI code assistants the context they need to make informed decisions across every project.
Build in Public, Ship in Private
Share learnings, patterns, and context openly while keeping client-specific projects private. Each site is its own git repository, independently deployable -- the pseudomonorepo is a development convenience, never a deployment requirement.
Packages from Authentic Need
Don't guess what should be shared. Develop true packages only when real developer needs prove the value. Our first: @lossless-group/lfm -- a shared markdown processing pipeline born from building the same render logic across six sites.
Sites in the Workspace
In progress
Nested astro-site
An Honest Reckoning
A pseudomonorepo is in between states. Here's what actually held up when our small team tried to maintain a workspace of ten-plus Astro sites — and what we quietly walked back.
What Survived
- Co-located development — all sites visible in one workspace for pattern comparison
- Git submodules — each site is its own repo, independently deployable
- Shared
context-v/documents (specs, blueprints, prompts, reminders) that guide development across sites - Cross-loadable context: site-specific files referenced via
@context-v/*when they apply elsewhere - Selective package publishing when something genuinely needs to be shared as a dependency
What We Walked Back
@knots/*as imported dependencies — too much abstraction overhead for the value- “Copy when you remember” — we usually didn't remember
- Style-free component patterns — sites diverge too much in design for generic components to work
Current stance: evolving toward more sharing, but only where it's justified. Markdown processing pipelines genuinely benefit from a shared package; UI components don't.
@lossless-group/lfm
Lossless Flavored Markdown — a shared remark/rehype pipeline for extended markdown processing. The first piece of the workspace that proved it deserved to be a real, published dependency rather than a copy-paste pattern.
remark-callouts
Normalizes Obsidian > [!type] Title callouts into directive nodes that any renderer can consume.
remark-citations
Transforms hex-code footnote identifiers ([^a1b2c3]) into sequentially-numbered citations with structured metadata — so authors never renumber when reordering.
One import, one tree
Bundles unified, remark-parse, remark-gfm, remark-directive, and custom plugins behind a single parseMarkdown() call.
import { parseMarkdown } from '@lossless-group/lfm';
const tree = await parseMarkdown(content);
// Citations attached to the tree after parsing
const citations = tree.data?.citations?.ordered ?? [];
// Each citation: index, title, url, source,
// publishedDate, rawPattern Packages: @knots/*
Not published packages. Workspace-local pattern references — source code you look at, copy from, and adapt. They exist as a cookbook of conventions for sites that need a starting point.
@knots/tokens Design token structure (colors, scales)
@knots/icons SVG icon helper pattern
@knots/astro Astro patterns: Button, AstroMarkdown, CodeBlock, Callout
@knots/svelte Svelte component patterns
@knots/brand-config Brand configuration type and CSS var helper
@knots/tailwind Tailwind preset/plugin (TW4 migration pending)
The @knots/astro markdown components are particularly useful as a starting point — mpstaton-site copied and adapted these for its content rendering.
Two Internal Reference Pages, Per Site
Every Astro Knots site ships with /brand-kit and /design-system pages that together replace what most teams use Storybook for. Components render in their real theme, mode, layout, and tokens — no parallel build, no drift.
Brand Kit (/brand-kit)
- Audience
- Stakeholders, brand reviewers, marketing
- Scope
- Brand essentials — colors, type, marks, signature layouts
- Update cadence
- Rarely — only when brand evolves
Design System (/design-system)
- Audience
- Developers, AI assistants, contributors
- Scope
- Exhaustive component catalog with variants, props, CSS contracts
- Update cadence
- Continuously — every new component lands here
Both pages use the standard BaseThemeLayout and surface the theme + mode toggle so reviewers can verify all three modes — light, dark, and vibrant — without leaving the page.
Quick Start
Always use pnpm — npm or yarn break workspace resolution.
# Install everything
pnpm install
# Run a site
pnpm --filter mpstaton-site dev
pnpm --filter hypernova-site dev
pnpm --filter cilantro-site dev
# Build a site
pnpm --filter mpstaton-site build
# If pnpm complains about GitHub Packages auth
GITHUB_TOKEN=$(gh auth token) pnpm installSelective Package Sharing.
Lossless Flavored Markdown: A Shared Processing Pipeline
When code genuinely needs to be shared -- not just copied -- we publish it. @lossless-group/lfm bundles unified, remark-parse, remark-gfm, remark-directive, and custom plugins into a single import. Sites install it as a real dependency from GitHub Packages or JSR.
Patterns Over Dependencies.
Copy, Adapt, Own: A Practical Component Strategy
Not everything should be a shared package. UI components, layouts, and styles are better copied and adapted per site. @knots/* pattern packages serve as a cookbook -- reference implementations you browse, copy into your site, and make your own. No runtime coupling, no abstraction overhead.
Independent Deployment.
Each Site Ships on Its Own Terms
Every project deploys directly from its own repository via Vercel -- no knowledge of the pseudomonorepo required. Published packages are installed from registries, not workspace links. The workspace is a development accelerator, never a deployment dependency.
Context-Driven Development.
Specs, Blueprints, and Prompts Guide Every Decision
The context-v/ directory holds living documentation -- formal specs, architecture blueprints, implementation prompts, and reminders -- that travels with the workspace. AI assistants and human collaborators alike can reference these documents to understand the why behind every pattern.