Static content generation using Rollup
This plugin allows to generate i18n summary and pages from yaml or json files to fetch them later in your app. This allows to create SPA blog using rollup and framework of your choise very easily.
Installation
npm i -D rollup-plugin-content# or yarn add -D rollup-plugin-content
Usage
Suppose you have the next structure of files (you are not forced to use this folder structure):
[user@laptop my-website]$ tree src/content/pages├── about│ ├── en.yml│ └── uk.yml├── friends│ ├── en.yml│ └── uk.yml└── notfound│ ├── en.yml│ └── uk.yml
And the sample file looks like this (to see full list of properties, check json schem file):
title: About blogcreatedAt: 2020-03-09T00:00:00.Zmeta: keywords: [software, opensource, just interesting content] description: some interesting information about the blogcontent: | Hello this is and interesting blog about software development
In order to load them in js, you need to include content
plugin in your rollup.config.js
;; input: 'src/app.js' output: format: 'es' dir: 'dist' sourcemap: true plugins: // other plugins
Later in your app create a service in src/services/pages.js
; // you can fetch a particular page { // const aboutPageUrl = pages.en.about; const response = await ; return response;} // and you can get a list of all pages sorted by createdAt desc! { const response = await ; return response}
Later in your app.js
:
; { const page = await ; console; const pages = await ; console // list of pages} ;
About Summaries
Summaries are very useful to create a list of articles, especially in the blog. This plugin iterates recursively over directories, extracts and collects details for each page. Also it creates 2 indexes: index by category and index by keywords. This allows to find pages very quickly. For example, to find all pages in the category frontend
; { const pages = await ; return pagesbyCategorycategory;} { const pagesAboutFrontend = await ; console;}
To see the list of propeties inside page summary items, check schema file.
Options
-
matches
, by default equals/\.summary$/
regexp that matches which imports to process -
langs
, by default equals['en']
validates which languages should be included. Lang should be a part of file (e.g.,en.json
,about.en.yml
) -
main
, containsSummaryOptions
for the main entry file. Sometimes it may be useful to restrict content of the main file and this field allows us to do this. -
pageSchema
, by default can be found here JSON schema to validate the page. So, you are saved from making a typo and spending hours trying to understand what is wrong -
parse
, by default equalscontent => JSON.parse(content)
parses file content into object, accepts file content and parsing context. -
fs
, by default uses nodejs filesystem may be useful if you want to implement in memmory filesystem. Must implement 2 methods:walkPath
andreadFile
. -
plugins
allows to pass content plugins. Every plugin has the next hooks:beforeParse(source: string, parsingContext: ParsingContext): void
,afterParse(item: object, parsingContext: ParsingContext): void
generate(rollup: PluginContext, context: GenerationContext): string | Promise<string>
In order to use this in typescript just include rollup-plugin-content/content.d.ts
in your tsconfig.json
Built-in plugins
This package contains summary
content plugin that allows to create a separate json of short summary info for all items. This is useful if you need to list all your pages in chronological order (e.g., in blog).
Summary plugin accepts either a configuration for summary or summarizer factory. It can be used to create search index json file using JavaScript full text search libraries like MiniSearch.
Can I use HTML inside?
Yes, you can use either gray-matter or xyaml-webpack-loader to use HTML in yaml files.
Config for xyaml-webpack-loader
Despite the name xyaml-webpack-loader supports rollup as well and can be used as a standalone parser:
;; input: 'src/app.js' output: // ... plugins: // ...
The nice thing about this package is that it allows you to use markdown in any field you need, not only in content section.
Config for gray-matter
Pass grayMatter
to parse
option of rollup-plugin-content and use gray-matter to define your content:
;; input: 'src/app.js' output: // ... plugins: // ...
Get the best of 2 packages
gray-matter supports custom parsers and this allows to combine xyaml-webpack-loader's parser with gray-matter:
;;; input: 'src/app.js' output: // ... plugins: // ...
Example
This plugin is used to generate CASL documentation. You can check how it's used to create pages and search index for client side full text search in rollup.config.js.
License
Copyright (c) 2020-present, Sergii Stotskyi