Numbers Produce Meaning

    content-maestro
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.1-alpha.19 • Public • Published

    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-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

    Install

    npm i content-maestro

    DownloadsWeekly Downloads

    62

    Version

    0.0.1-alpha.19

    License

    ISC

    Unpacked Size

    120 kB

    Total Files

    11

    Last publish

    Collaborators

    • julian.cataldo