{"fileId":"e05e445fb74924b7edaa172ea87786ed827ef7792473dcd442da7f808c23394b","type":"Contented","path":"/api","modifiedDate":1696943516077,"sections":[],"fields":{"title":"API Reference","description":"To ease the authoring process, content write creates a preview of your content on localhost:3000. The preview comes with a basic content navigation tree (left), table of contents (right), and prose formatting (center).","editOnGitHubLink":"https://github.com/levaintech/contented/edit/main/packages/contented-example/docs/03-api.md"},"headings":[{"depth":1,"headingId":"api-reference","title":"API Reference","children":[{"depth":2,"headingId":"contented-write","title":"contented write","children":[]},{"depth":2,"headingId":"contented-generate","title":"contented generate","children":[]},{"depth":2,"headingId":"contented-build","title":"contented build","children":[]},{"depth":2,"headingId":"contented-configuration","title":"Contented Configuration","children":[{"depth":3,"headingId":"contentedconfigmjs","title":"contented.config.mjs","children":[]}]}]}],"html":"

API Reference

\n

contented write

\n

To ease the authoring process, content write creates a preview of your content on localhost:3000. The preview comes\nwith a basic content navigation tree (left), table of contents (right), and prose formatting (center).

\n

This website, the current one you're looking at right now is the result of contented write.

\n

contented generate

\n

Generates the static preview website that can be published to GitHub Pages, Netlify, or Vercel! Minimally, you need to\nconfigure your package.json with these fields:

\n

package.json:

\n
{\n  \"scripts\": {\n    \"generate\": \"contented generate\"\n  },\n  \"devDependencies\": {\n    \"@contentedjs/contented\": \"latest\"\n  }\n}
\n

contented.config.mjs:

\n
/** @type {import('@contentedjs/contented').ContentedConfig} */\nconst config = {\n  preview: {\n    url: 'https://contented.dev',\n    name: 'Contented',\n    github: {\n      url: 'https://github.com/levaintech/contented',\n    },\n  },\n  processor: {\n    pipelines: [\n      {\n        type: 'Doc',\n        pattern: '**/*.md',\n        processor: 'md',\n      },\n    ],\n  },\n};\n\nexport default config;
\n

Netlify TOML:

\n
[build]\npublish = \".contented/.preview/out\"\ncommand = \"npm run generate\"
\n

Vercel Settings:

\n
FRAMEWORK PRESET    = Next.js\nBUILD COMMAND       = npm run generate\nOUTPUT DIRECTORY    = .contented/.preview/out
\n

contented build

\n

Generates the ./dist output that can be published into the NPM registry for creating a derivative site. Minimally, you\nneed to configure your package.json with these fields:

\n
{\n  \"name\": \"@your-scope/your-npm-package\",\n  \"files\": [\"dist\"],\n  \"main\": \"dist/index.js\",\n  \"scripts\": {\n    \"build\": \"contented build\"\n  },\n  \"devDependencies\": {\n    \"@contentedjs/contented\": \"latest\"\n  }\n}
\n

Run contented build to compiled your markdown into index.js and *.json, output to the dir: ./dist.\nYou can npm publish into any registry of your choice. You can easily npm i @your-scope/your-npm-package and use the\nprocessed content on any downstream site.

\n
import { Index } from '@your-scope/your-npm-package';
\n

Contented Configuration

\n

The anatomy of a contented package, with just 2 configuration files, and you are good from the get-go! Contented\nautomatically ignore files in your .gitignore and .contentedignore.

\n
\n

You should also add a .gitignore too with echo \"dist\\n.contented\" > .gitignore. (Okay fine! 3 files it is. Ughhhh)

\n
\n

contented.config.mjs

\n
export interface ContentedConfig {\n  preview: {\n    url?: string;\n    name?: string;\n    github?: {\n      url?: string;\n    };\n  };\n  processor: {\n    /**\n     * The root directory of your contented markdown.\n     */\n    rootDir?: string;\n    /**\n     * Customize the output path. Editing this will cause contented-preview to break.\n     */\n    outDir?: string;\n    /**\n     * Contented processing pipeline\n     */\n    pipelines: Pipeline[];\n  };\n}\n\nexport interface Pipeline {\n  type: string;\n  pattern: string;\n  processor: 'md';\n  fields?: {\n    [name: string]: PipelineField;\n  };\n  transform?: (file: FileContent) => Promise<FileContent>;\n}
\n

Example

\n
/** @type {import('@contentedjs/contented').ContentedConfig} */\nmodule.exports = {\n  preview: {\n    url: 'https://contented.dev',\n    name: 'Contented',\n    github: {\n      url: 'https://github.com/levaintech/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        type: 'Lorem',\n        pattern: 'lorem/**/*.md',\n        processor: 'md',\n        fields: {\n          title: {\n            type: 'string',\n          },\n        },\n        transform: (file) => {\n          file.sections = file.sections.slice(1);\n          return file;\n        },\n      },\n    ],\n  },\n};
"}