{"id":16933679,"url":"https://github.com/stalniy/rollup-plugin-content","last_synced_at":"2025-04-05T14:40:18.947Z","repository":{"id":46333198,"uuid":"246096058","full_name":"stalniy/rollup-plugin-content","owner":"stalniy","description":"Rollup plugin to generate content and its summaries for i18n static sites","archived":false,"fork":false,"pushed_at":"2023-01-05T09:32:25.000Z","size":1358,"stargazers_count":2,"open_issues_count":8,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-18T11:02:42.603Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stalniy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-09T17:12:04.000Z","updated_at":"2023-08-10T13:30:54.000Z","dependencies_parsed_at":"2023-02-03T23:01:54.341Z","dependency_job_id":null,"html_url":"https://github.com/stalniy/rollup-plugin-content","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stalniy%2Frollup-plugin-content","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stalniy%2Frollup-plugin-content/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stalniy%2Frollup-plugin-content/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stalniy%2Frollup-plugin-content/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stalniy","download_url":"https://codeload.github.com/stalniy/rollup-plugin-content/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353679,"owners_count":20925324,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T20:50:07.838Z","updated_at":"2025-04-05T14:40:18.927Z","avatar_url":"https://github.com/stalniy.png","language":"TypeScript","funding_links":[],"categories":["Plugins"],"sub_categories":["Templating"],"readme":"# Static content generation using Rollup\n\nThis 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.\n\n## Installation\n\n```sh\nnpm i -D rollup-plugin-content\n# or\nyarn add -D rollup-plugin-content\n```\n\n## Usage\n\nSuppose you have the next structure of files (you are not forced to use this folder structure):\n\n```sh\n[user@laptop my-website]$ tree src/content/pages\n├── about\n│   ├── en.yml\n│   └── uk.yml\n├── friends\n│   ├── en.yml\n│   └── uk.yml\n└── notfound\n│   ├── en.yml\n│   └── uk.yml\n```\n\nAnd the sample file looks like this (to see full list of properties, check [json schem file](./src/schema.ts#L12)):\n\n```yml\ntitle: About blog\ncreatedAt: 2020-03-09T00:00:00.Z\nmeta:\n  keywords: [software, opensource, just interesting content]\n  description: some interesting information about the blog\ncontent: |\n  Hello this is and interesting blog about software development\n```\n\nIn order to load them in js, you need to include `content` plugin in your `rollup.config.js`\n\n```js\nimport yaml from 'js-yaml';\nimport { content } from 'rollup-plugin-content';\n\nexport default {\n  input: 'src/app.js',\n  output: {\n    format: 'es',\n    dir: 'dist',\n    sourcemap: true,\n  },\n  plugins: [\n    content({\n      langs: ['en', 'uk'],\n      parse: yaml.load, // by default uses `JSON.parse`\n      plugins: [\n        summary({\n          fields: ['title', 'createdAt']\n        })\n      ]\n    }),\n    // other plugins\n  ]\n}\n```\n\nLater in your app create a service in `src/services/pages.js`\n\n```js\nimport { pages, summaries } from '../content/pages.summary';\n\n// you can fetch a particular page\nexport async function getPage(lang, name) {\n  // const aboutPageUrl = pages.en.about;\n  const response = await fetch(pages[lang][name]);\n  return response.json();\n}\n\n// and you can get a list of all pages sorted by createdAt desc!\nexport async function getPages(lang) {\n  const response = await fetch(summaries[lang]);\n  return response.json()\n}\n```\n\nLater in your `app.js`:\n\n```js\nimport { getPage, getPages } from './services/pages';\n\nasync function main() {\n  const page = await getPage('en', 'about');\n  console.log(page.title, page.content);\n\n  const pages = await getPages('en');\n  console.log(pages.items) // list of pages\n}\n\nmain();\n```\n\n## About Summaries\n\nSummaries 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`\n\n```js\nimport { getPages } from './services/pages';\n\nasync function getPagesByCategory(lang, category) {\n  const pages = await getPages(lang);\n  return pages.byCategory[category].map(index =\u003e pages.items[index]);\n}\n\nasync function main() {\n  const pagesAboutFrontend = await getPagesByCategory('en', 'frontend');\n\n  console.log(pagesAboutFrontend);\n}\n```\n\nTo see the list of propeties inside page summary items, check [schema file](./src/schema.ts#L1).\n\n## Options\n\n* `matches`, by default equals `/\\.summary$/`\n  regexp that matches which imports to process\n* `langs`, by default equals `['en']`\n  validates which languages should be included. Lang should be a part of file (e.g., `en.json`, `about.en.yml`)\n* `main`, contains `SummaryOptions` for the main entry file.\n  Sometimes it may be useful to restrict content of the main file and this field allows us to do this.\n* `pageSchema`, by default can be found [here](./src/schema.ts#L12)\n  JSON schema to validate the page. So, you are saved from making a typo and spending hours trying to understand what is wrong\n* `parse`, by default equals `content =\u003e JSON.parse(content)`\n  parses file content into object, accepts file content and parsing context.\n* `fs`, by default uses nodejs filesystem\n  may be useful if you want to implement in memmory filesystem. Must implement 2 methods: `walkPath` and `readFile`.\n* `plugins`\\\n  allows to pass content plugins. Every plugin has the next hooks:\n\n  * `beforeParse(source: string, parsingContext: ParsingContext): void`,\n  * `afterParse(item: object, parsingContext: ParsingContext): void`\n  * `generate(rollup: PluginContext, context: GenerationContext): string | Promise\u003cstring\u003e`\n\nIn order to use this in typescript just include `rollup-plugin-content/content.d.ts` in your `tsconfig.json`\n\n```json\n{\n  \"include\": [\n    // other includes\n    \"node_modules/rollup-plugin-content/content.d.ts\"\n  ]\n}\n```\n\n## Built-in plugins\n\nThis 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).\n\nSummary 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](https://github.com/lucaong/minisearch).\n\n## Can I use HTML inside?\n\nYes, you can use either [gray-matter] or [xyaml-webpack-loader] to use HTML in yaml files.\n\n### Config for xyaml-webpack-loader\n\nDespite the name [xyaml-webpack-loader] supports rollup as well and can be used as a standalone parser:\n\n```js\nimport { parse } from 'xyaml-webpack-loader/parser';\nimport { content } from 'rollup-plugin-content';\n\nexport default {\n  input: 'src/app.js',\n  output: {\n    // ...\n  },\n  plugins: [\n    // ...\n    content({\n      langs: ['en', 'uk'],\n      parse\n    }),\n  ]\n}\n```\n\nThe nice thing about this package is that it allows you to use markdown in any field you need, not only in content section.\n\n### Config for gray-matter\n\nPass `grayMatter` to `parse` option of rollup-plugin-content and use [gray-matter] to define your content:\n\n```js\nimport matter from 'gray-matter';\nimport { content } from 'rollup-plugin-content';\n\nexport default {\n  input: 'src/app.js',\n  output: {\n    // ...\n  },\n  plugins: [\n    // ...\n    content({\n      langs: ['en', 'uk'],\n      parse: matter\n    }),\n  ]\n}\n```\n\n### Get the best of 2 packages\n\n[gray-matter] supports custom parsers and this allows to combine [xyaml-webpack-loader]'s parser with gray-matter:\n\n```js\nimport parser from 'xyaml-webpack-loader/parser';\nimport matter from 'gray-matter';\nimport { content } from 'rollup-plugin-content';\n\nexport default {\n  input: 'src/app.js',\n  output: {\n    // ...\n  },\n  plugins: [\n    // ...\n    content({\n      langs: ['en', 'uk'],\n      parse: content =\u003e matter(content, {\n        language: 'xyaml',\n        engines: {\n          xyaml: parser\n        }\n      })\n    }),\n  ]\n}\n```\n\n[gray-matter]: https://github.com/jonschlinkert/gray-matter\n[xyaml-webpack-loader]: https://github.com/stalniy/xyaml-webpack-loader\n\n## Example\n\nThis plugin is used to generate [CASL documentation](https://stalniy.github.io/casl/). You can check how it's used to create pages and search index for client side full text search in [rollup.config.js](https://github.com/stalniy/casl/blob/master/docs-src/rollup.config.js#L144).\n\n## License\n\n[MIT License](http://www.opensource.org/licenses/MIT)\n\nCopyright (c) 2020-present, Sergii Stotskyi\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstalniy%2Frollup-plugin-content","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstalniy%2Frollup-plugin-content","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstalniy%2Frollup-plugin-content/lists"}