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).
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-hoistLaunch 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:serveCreate 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-remarkTypical 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
Configuration
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