Content Maestro 💁‍♂️📚

A text based, structured content framework, for edition and consumption.

Warning: Under heavy development

Highlights

• Manage your content in a predictable way
• Prevents entropy for ever growing knowledge base
• Future-proof: based on standards, idioms and popular tools
• Transform and serve your content
• Generate type-safe import Helpers
• Agnostic API: target any consumer type

You might have 10 wiki entries, it's easy to refactor for a category name typo.
But what if we have hundreds of entries accross dozens of differents collections types?

That's where Content Maestro shines, by establishing a schema first based workflow.
The whole content pipeline originate from a seed: your schemas definitions.

Current state of DX for code edition is phenomenal thanks to TypeScript, languages servers, linting tools, smart IDEs…
Thankfully, we are making some progress regarding content management and EX (editor experience).

• Content Maestro 💁‍♂️📚
  • Highlights
  • Installation
    • Create project
    • Launch content server & front end
    • Create content
    • Recommended VS Code extensions
    • Typical structure
  • Content ingestion
    • Helper
      • Astro template
  • Consumers
  • Demo
  • Configuration
• Let's get into the details
  • For whom?
  • What's in the box?
    • Markdown
      • Checking (linting + validation)
      • Transformer
  • How does it works? An eagle view

Installation

Create project

# Create the parent housing folder for your project
mkdir ./my-project && cd ./my-project

# Content Maestro boilerplate + CLI
pnpx degit \
JulianCataldo/content-maestro/demo/content-base ./content-base

# (Optional) Demo front-end content consumer
# `content-base` package is linked-imported in this front-end
pnpx degit \
JulianCataldo/content-maestro/demo/front-astro ./front-astro

# Bootstrap all dependencies
pnpm install --recursive --shamefully-hoist

Launch content server & front end

# Terminal A — Content server
cd ./content-base
pnpm run start

# Terminal B — Consumer web GUI
cd ./front-astro
# Development mode
pnpm run dev

# -OR- pack + launch server side rendered website
pnpm run build:serve

Create content

# Terminal C — Content creation CLI utilities
cd ./content-base

# Bootstrap a singleton entity
pnpm maestro create profile

# Bootstrap a collection of entities
pnpm maestro create people person
#                       ↑      ↑
# Collection name ——————·      |
# Entity singular name ————————·
#
# Yields:
#
# content/people
# ├── person.schema.yaml     (basic schema)
# └── voice-hay-lif          (random words)
#     ├── body.md            (basic frontmatter + markdown)
#     └── meta.yaml          (basic extra metadata)

# ··············································································

# Create a new entity inside an existing collection
pnpm maestro create people elisabeth
#                       ↑        ↑
# Collection name ——————·        |
# New entity name ———————————————·
#
# Yields:
#
# content/people
# └── elisabeth
#     ├── […].md            (schema generated fake data frontmatter + markdown)
#     └── […].yaml          (schema generated fake metadata)

Recommended VS Code extensions

code --install-extension redhat.vscode-yaml
code --install-extension unifiedjs.vscode-remark

Typical structure

Example project setup is made of:

• A package folder where all your content with its dedicated environment lives:
  • The content server, which can act both for dev. and prod.
  • Content helpers, exported as a package for consumers to import
  • Pre-configured local dev. static tooling for edition
• (Optional) A folder with your front end consumer, could be anything:
  Nuxt, Next, Gatsby, Astro, plain TypeScript…
  Here we use Astro.

Content ingestion

As for now, supports: pure Markdown* and YAML.

*with advanced features like GFM, directives, TOC…

Helper

import content from 'content/get';

const articles = await content.getArticles();

console.log(articles?.someNamedArticle);
console.log(articles?.someNamedArticle?.main?.body);

Astro template

See demo front-end implementations.
Pre-configured for SSR bundling, then serve.

Front-end works in concert with content server and will fast-refresh its changes in dev. mode.

---
import content from 'content/get';

import { Markup } from 'astro-remote';
import Gallery from 'src/components/Gallery.astro';
import Link from 'src/components/Link.astro';

const articles = await content.getArticles();

const someNamedArticle = articles?.someNamedArticle
const content = someNamedArticle?.main?.body;
const title = someNamedArticle?.main?.frontmatter?.title;
const someMeta = someNamedArticle?.meta?.foo;

/* Augment markup by mapping your Astro / React / Vue / Svelte components
   Server-side rendering only (no client-side hydration) */
const components = { Gallery, 'a': Link, /* … */ };
---

{ title && <h1>{title}</h1> }

{ content && <Markup {content} {components} /> }

{ someMeta || 'nothing…' }

<!-- ... -->

Consumers

You could really use anything on the other side of the wire, though, Content Maestro is made with the Astro framework in mind, as it provides easy way to integrate and "augment" remote markup.
Content helpers are just plain typescript functions, with no ties, outside of AJV.

Demo

See the demo workspace

Configuration

See the Configuration API

Let's get into the details

For whom?

Mainly for us, developers 🤓.
We enjoy building tools that make content editing simpler for non-technical people.
Still, for us, text-based editing is unbeatable.
However, this presents a challenge: how do we keep track of structural changes?
How can we make this predictable for content consumers like your wiki, documentation, blog, web garden, or any server-rendered or static website?

What's in the box?

• Sensible defaults for a quick new project bootstrap
• State-of-the-art Markdown (and friends) environment
• A command line initializer, with options
• A command line editing server
• Fake entries mock server, with valid content for lorem ipsum purposes
• A command line assistant for scaffolding new entries
• An open gate for adding your own transformers
• A graphical interface for content preview / problems reviews
• Linting / checking pre-configured and orchestrated for you
• Refactoring assistance, thanks to all your IDE toolings

Markdown

These are the already bundled Mardown transformers

Checking (linting + validation)

• Preset — Recommended
• Preset — Style Guide
• Preset — Consistent
• YAML frontmatter schema validation

Transformer

• Transform markdown directives to custom components
• Load GitHub-flavored Markdown features
• Extract YAML frontmatter
• Convert to formatted HTML
• Pass <Components /> for front-end to handle
• Bundle and build entries static JSONs

How does it works? An eagle view

See the diagram here