nuxt/content
Intro
See Documentation for a full list of features. There are 2 highlights
- Git-based headless CMS (read from file system) + MongoDB-like Query
- Nice, pluginable Markdown rendering system
Here are the ones I found particularly useful:
- Full-text search
- Static Site Generation
- MongoDB-like Query API
- Table of Content
- Support for Markdown, CSV, YAML, JSON, XML
- Extensibility with plugins
This module acts as a git-based headless CMS allowing user to query files from file system and display them nicely (with code highlight and latex). External CMS is also supported, because query (git-based headless CMS) and rendering are 2 separate things. Using external (remote) CMS doesn't mean you can't render the content any more.
There are a bunch of plugins you can choose from to improve the experience and functionalities. If all you want is standard documentation without too much customization, then this is perfect.
Docs Theme
It contains a theme for documentation which many nuxt documentations are built on. It's basically a starter template where user just need to write markdown files and the documentation is rendered nicely. Ths Docs theme is perfect for simple documentation that doesn't contain too many functionalities and pages. Nuxt has lots of functionalities and their documentations are divide into many separate modules.
Customization and Configuration
If you don't use the Docs Theme, you can write your own layout like regular nuxt apps. The tag <nuxt-content />
will render the markdown file you passed to it.
This means that in a vue file, all you do is fetching the document content and pass the content to <nuxt-content document="page" />
. It's simple and clean to use, but you may have custom configurations you want to make, which can be done using plugins (local or external).
See [Configuration] for what can be customized. All configurations can be set in nuxt.config.js
.
There are many configuration options, for example the liveEdit
boolean attribute enables you to edit markdown within browser in development. The edited file will be saved to the file system which is convenient for small changes.
Markdown
The markdown configuration is definitely the most important option which let's you customize how you want your markdown file to be rendered using plugins, both external plugin and local plugin are supported.
Sample
nuxt.config.js
export default {
content: {
markdown: {
remarkPlugins: [
['remark-emoji', { emoticon: true }],
'~/plugins/my-custom-remark-plugin.js' // local plugin
]
}
}
}
The following plugins enables math equation to be rendered.
...
content: {
markdown: {
prism: {
theme: false,
},
remarkPlugins: ['remark-math'],
rehypePlugins: ['rehype-mathjax'],
},
},
...
There are a list of remark and rehype plugins.
Code Highlight
Code Highlight is a must for programmers and one of the reason I don't use medium to write blog.
Prism is supported by default.
highlight.js is also supported.
Hooks
They are like middlewares or setup and teardown functions, which are run in different stages or Markdown rendering.
content:file:beforeParse
e.g. you may change file content before parsing it.
content:file:beforeInsert
After parsing, you many add attributes (e.g. reading time estimate) to the parsed document.
content:options
Change options if necessary.
Handling Hot Reload
Write plugins to do anything during hot reload during development.
Usage
See Snippets for sample usage.