{"id":"562b0961fd8bc3bfd6224eb4c7563cc9c3ce569a9062ea81b0ea4b572c3936f6","type":"Contented","path":"/","modifiedDate":1686373756200,"sections":[],"fields":{"title":"Contented"},"html":"

Contented

\n

Contented is a Markdown-based authoring workflow that encourage developer authoring within\nits contextual Git repository. npm i @birthdayresearch/contented

\n

With a headless design of 1 config file contented.config.js, developers can start writing\ntheir markdown content and preview it on their localhost contented write. Choosing convention over\nconfiguration reduces HTML/UI clutter, allowing developers to focus on authoring.

\n

Authored content can be continuously delivered (CD) into a hosted static site (e.g., GitHub Pages/Netlify/Vercel) for\npreview contented generate. As code drift, so does documentation; this allows each pull request to have an\naccompanying sharable preview of the documentation. With CD, it effectively shift-left your documentation workflow and\nchecks it is compilable and presentable.

\n

By encouraging authoring next to the source (in the same git repo), developers can contextually document changes as they\ndevelop. All domain-specific changes will go into the main branch with one Git Pull Request.

\n

With contented build, you can compile your markdown into sources index.js and *.json. That output\ninto ./dist. npm publish them into any registry of your choice, for you can\neasily npm i @your-scope/your-npm-package and use the processed content on any of your downstream sites. Easily\npulling up-to-date content and prose from individual domain-specific repositories and re-presented. Think microservices,\nbut for your prose!

\n

Motivation

\n

If you don’t make it easy to get something done (authoring), nobody will go out of their way to get it done perfectly\nevery time. Turn it into a GitOps workflow and give people the necessary tools and power to get it done perfectly every\nsingle time — everyone will get it done, as now there is no other way else to get it done. An efficient workflow\nnaturally satisfies.

\n

Just Another SSG?

\n

This is not a static site generator. This is a markdown processor workflow with a built-in static site generator.\nThe outcome we're trying to achieve is\nthis @birthdayresearch/contented-example/dist

\n
\n

See Contented Limitations

\n
\n

Powered By

\n\n

Getting Started

\n

Your docs can be anywhere as long as contented is configured to pick them up.

\n
repo/\n├─ packages/**\n├─ docs/\n│  ├─ 01:Title 1/*.md\n│  ├─ 02:Title 2/*.md\n│  ├─ 03:Title 3/\n│  │  ├─ 01:Subtitle 1/*.md\n│  │  ├─ 02:overview.md\n│  │  └─ 03:faq.md\n│  └─ package.json\n├─ contented.config.js\n├─ package.json\n└─ README.md
\n

package.json

\n
{\n  \"name\": \"@birthdayresearch/contented-example\",\n  \"version\": \"0.0.0\",\n  \"private\": false,\n  \"files\": [\"dist\"],\n  \"main\": \"dist/index.js\",\n  \"scripts\": {\n    \"write\": \"contented write\",\n    \"generate\": \"contented generate\",\n    \"build\": \"contented build\"\n  },\n  \"devDependencies\": {\n    \"@birthdayresearch/contented\": \"latest\"\n  }\n}
\n

contented.config.js

\n
/** @type {import('@birthdayresearch/contented').ContentedConfig} */\nmodule.exports = {\n  preview: {\n    url: 'https://contented.dev',\n    name: 'Contented',\n    github: {\n      url: 'https://github.com/BirthdayResearch/contented',\n    },\n  },\n  processor: {\n    pipelines: [\n      {\n        type: 'Docs',\n        pattern: 'docs/**/*.md',\n        processor: 'md',\n        fields: {\n          title: {\n            type: 'string',\n            required: true,\n            resolve: (s) => s ?? 'Contented',\n          },\n          description: {\n            type: 'string',\n          },\n          tags: {\n            type: 'string[]',\n          },\n        },\n        transform: (file) => {\n          file.path = file.path.replaceAll(/^\\/docs\\/?/g, '/');\n          file.sections = file.sections.slice(1);\n          return file;\n        },\n      },\n    ],\n  },\n};
\n

Examples

\n","headings":[{"depth":1,"id":"contented","title":"Contented","children":[{"depth":2,"id":"motivation","title":"Motivation","children":[{"depth":3,"id":"just-another-ssg","title":"Just Another SSG?","children":[]}]},{"depth":2,"id":"powered-by","title":"Powered By","children":[]},{"depth":2,"id":"getting-started","title":"Getting Started","children":[{"depth":3,"id":"examples","title":"Examples","children":[]}]}]}]}