{"id":16747479,"url":"https://github.com/roydukkey/docusaurus-theme-frontmatter","last_synced_at":"2025-03-23T15:31:05.012Z","repository":{"id":44353206,"uuid":"445389034","full_name":"roydukkey/docusaurus-theme-frontmatter","owner":"roydukkey","description":"Docusaurus theme plugin to expose front matter through a component hook","archived":false,"fork":false,"pushed_at":"2022-07-09T15:19:56.000Z","size":22,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-15T18:14:10.505Z","etag":null,"topics":["docusaurus","docusaurus-plugin","docusaurus-v2","frontmatter","graymatter"],"latest_commit_sha":null,"homepage":"","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/roydukkey.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["roydukkey"]}},"created_at":"2022-01-07T03:44:06.000Z","updated_at":"2024-09-30T21:07:56.000Z","dependencies_parsed_at":"2022-08-29T21:42:14.928Z","dependency_job_id":null,"html_url":"https://github.com/roydukkey/docusaurus-theme-frontmatter","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roydukkey%2Fdocusaurus-theme-frontmatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roydukkey%2Fdocusaurus-theme-frontmatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roydukkey%2Fdocusaurus-theme-frontmatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roydukkey%2Fdocusaurus-theme-frontmatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roydukkey","download_url":"https://codeload.github.com/roydukkey/docusaurus-theme-frontmatter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245122720,"owners_count":20564361,"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":["docusaurus","docusaurus-plugin","docusaurus-v2","frontmatter","graymatter"],"created_at":"2024-10-13T02:10:06.971Z","updated_at":"2025-03-23T15:31:04.660Z","avatar_url":"https://github.com/roydukkey.png","language":"TypeScript","readme":"# docusaurus-theme-frontmatter\n\nThis package enhances the Docusaurus classic theme by exposing the [docs](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter), [blog](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog#markdown-front-matter), and [pages](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-pages) front matter to the following components and their children:\n\n* [BlogPostPage](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme/BlogPostPage)\n* [DocItem](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme/DocItem)\n* [MDXPage](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme/MDXPage)\n\nFurthermore, this allows you to define and access ***custom*** front matter.\n\n[![Release Version](https://img.shields.io/npm/v/docusaurus-theme-frontmatter.svg)](https://www.npmjs.com/package/docusaurus-theme-frontmatter)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n## Install\n\n```sh\nyarn add docusaurus-theme-frontmatter\n```\n\nThen, include the plugin in your `docusaurus.config.js` file.\n\n```diff\n// docusaurus.config.js\nmodule.exports = {\n  ...\n+ themes: ['docusaurus-theme-frontmatter'],\n  ...\n}\n```\n\n### TypeScript support\n\nTo enable TypeScript support, the TypeScript configuration should be updated to add the `docusaurus-theme-frontmatter` type definitions. This can be done in the `tsconfig.json` file:\n\n```diff\n{\n  \"extends\": \"@tsconfig/docusaurus/tsconfig.json\",\n  \"compilerOptions\": {\n    ...\n+    \"types\": [\"docusaurus-theme-frontmatter\"]\n  }\n}\n```\n\n## How to use\n\nThe `useFrontMatter()` hook is made available to any of your components through the `@theme/useFrontMatter` import. For example, you might have a component that creates a gallery of images.\n\n```mdx\n---\ntitle: Miniature fairy doors of NYC\nhide_table_of_contents: true\ngallery:\n  - /images/117-first-avenue.jpg\n  - /images/lower-east-side.jpg\n  - /images/my-guinness.jpg\n  - /images/hundred-years.jpg\n---\nimport Galley from '@theme/Galley';\n\n\u003cGalley /\u003e\n```\n\n```jsx\nimport React from 'react';\nimport ImageGallery from 'react-image-gallery';\nimport useFrontMatter from '@theme/useFrontMatter';\n\nexport default function GalleyComponent () {\n  const { gallery } = useFrontMatter();\n\n  if (Array.isArray(gallery)) {\n    const images = gallery.map((image) =\u003e ({\n      original: image\n    }));\n\n    return \u003cImageGallery items={images} /\u003e;\n  }\n\n  return null;\n}\n```\n\n## Public API\n\n### `useFrontMatter\u003cT extends FrontMatter\u003e()`\n\nReturns the front matter for the current context.\n\n```ts\nimport useFrontMatter from '@theme/useFrontMatter';\n\ninterface CustomFrontMatter {\n  gallery?: string[];\n}\n\nconst MyComponent = () =\u003e {\n  const { gallery } = useFrontMatter\u003cCustomFrontMatter\u003e();\n  return (\u003c... /\u003e);\n}\n```\n\n### `Context`\n\nThe current front matter context.\n\nGenerally, this is something to be left alone and operates behind the scenes. This is how it is used to [enhance DocItem](https://github.com/roydukkey/docusaurus-theme-frontmatter/blob/master/src/theme/DocItem.tsx) scaffolding the hook:\n\n```js\nimport { Context } from '@theme/useFrontMatter';\nimport DocItem from '@theme-init/DocItem';\nimport React from 'react';\n\nexport default (props) =\u003e \u003cContext.Provider value={props.content.frontMatter}\u003e\n\t\u003cDocItem {...props} /\u003e\n\u003c/Context.Provider\u003e;\n```\n\n### `FrontMatter`, `DocItemFrontMatter`, `BlogPostPageFrontMatter`, `MDXPageFrontMatter`\n\nThese types are provided to assist in describing the values returned by the `useFrontMatter()` hook.\n\n```ts\nimport useFrontMatter from '@theme/useFrontMatter';\nimport type { DocItemFrontMatter } from '@theme/useFrontMatter';\n\nconst MyComponent = () =\u003e {\n  const { id, title, keywords } = useFrontMatter\u003cDocItemFrontMatter\u003e();\n  return (\u003c... /\u003e);\n}\n```\n\n## Project Longevity\n\nThis project was originally created to provide a useful feature that was lacking in Docusaurus v2. Since the release of this plugin, the Docusaurus team has began a [plan to expose FrontMatter](https://github.com/facebook/docusaurus/issues/6885) and other data through hooks. So long their resulting work provides access to **custom** front matter, this project is likely to deprecate. However until that day comes, I will do my best to keep this project up-to-date with upstream changes.\n\nHere are some issues to review if you want to see where all this is headed:\n\n* [RFC: allow routes to declare a React context](https://github.com/facebook/docusaurus/issues/6885)\n* [refactor(docs,theme): split DocItem comp, useDoc hook](https://github.com/facebook/docusaurus/pull/7644)\n* [refactor(theme): split BlogPostItem into smaller theme subcomponents](https://github.com/facebook/docusaurus/pull/7716)\n","funding_links":["https://github.com/sponsors/roydukkey"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froydukkey%2Fdocusaurus-theme-frontmatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froydukkey%2Fdocusaurus-theme-frontmatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froydukkey%2Fdocusaurus-theme-frontmatter/lists"}