{"id":16014871,"url":"https://github.com/kitten/react-static-plugin-md-pages","last_synced_at":"2025-03-18T03:30:33.227Z","repository":{"id":63877470,"uuid":"241752992","full_name":"kitten/react-static-plugin-md-pages","owner":"kitten","description":"react-static plugin to create nested pages from a given source directory","archived":false,"fork":false,"pushed_at":"2022-11-28T05:01:18.000Z","size":190,"stargazers_count":8,"open_issues_count":4,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-28T06:31:11.339Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/kitten.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-02-19T23:55:04.000Z","updated_at":"2024-03-15T13:25:12.000Z","dependencies_parsed_at":"2022-11-28T06:15:44.557Z","dependency_job_id":null,"html_url":"https://github.com/kitten/react-static-plugin-md-pages","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitten%2Freact-static-plugin-md-pages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitten%2Freact-static-plugin-md-pages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitten%2Freact-static-plugin-md-pages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitten%2Freact-static-plugin-md-pages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kitten","download_url":"https://codeload.github.com/kitten/react-static-plugin-md-pages/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243896350,"owners_count":20365362,"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-08T15:05:23.818Z","updated_at":"2025-03-18T03:30:32.953Z","avatar_url":"https://github.com/kitten.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# react-static-plugin-md-pages\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/kitten/react-static-plugin-md-pages#maintenance-status\"\u003e\n    \u003cimg alt=\"Maintenance Status\" src=\"https://img.shields.io/badge/maintenance-experimental-blueviolet.svg\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003e A [react-static](https://react-static.js.org) plugin to create nested pages from a given source\n\u003e directory.\n\n## Install\n\n```sh\n$ yarn add react-static-plugin-md-pages\n# or\nnpm install --save react-static-plugin-md-pages\n```\n\n## Usage\n\nAdd the plugin to your `static.config.js` in the plugins array.\n\n```js\n// static.config.js\nexport default {\n  plugins: [\n    [\n      'react-static-plugin-md-pages',\n      {\n        location: './docs', // path to markdown files' directory\n        pathPrefix: '', // prefix for added react-static routes (if any)\n        template: './src/template.js', // path to React template component\n        remarkPlugins: [], // add additional remark plugins here\n      }\n    ]\n  ]\n};\n```\n\nYour markdown file may contain frontmatter data. This data will be\nreflected in the data you'll get from this plugin's [React API](#react-api).\n\nAn example will look like this:\n\n```\n---\ntitle: architecture\norder: 1\ntemplate: ../src/components/template.js\n---\n```\n\nAll of these properties are **optional**. The `title` may be used to change\nthe page's title, but by default the plugin will generate a title from your\nfirst `h1` heading in your markdown file.\n\nThe `order` property specifies the order in which your markdown files will\nbe sorted in, which will be reflected in the [React API](#react-api) as\nwell.\n\nLastly, the `template` property may be used to override the default React template component\nthat this specific page is using. The path must be relative to the current file.\n\n### Default Markdown Transformations\n\nThere are a couple of changes and features that will be applied to your markdown content\nautomatically. It's best to be aware of them before adding your own `remark` plugins.\n\n### Relative Links Fixes\n\nIf you're adding links to your markdown files they'll be transformed to automatically point\nat the `react-static` routes this plugin creates, so that your markdown files may remain compatible\nwith GitHub for instance. These links will be transformed:\n\n```md\n[Some link](./other-route.md)\n[Some other link](./folder/README.md)\n```\n\nAnd end up being this in `react-static`:\n\n```md\n[Some link](./other-route)\n[Some other link](./folder)\n```\n\n\u003e _Note_: This does not apply to `\u003ca\u003e` tags in your markdown file!\n\n### Automatic Image Importing\n\nWhen you're adding images to your markdown, they'll be automatically imported and sent through\nthe Webpack pipeline, so you won't have to reference images in your public folder absolutely.\n\n```md\n![This image will be imported!](./some-logo.png)\n```\n\n\u003e _Note_: This does not apply to `\u003cimg\u003e` tags in your markdown file!\n\n### Addings anchor `id` props to headings\n\nAll headings (`h1`, `h2`, `h3`, ...) will have an added `id` prop that contains their sluggified\nstring contents. The slugger we use is `github-slugger`.\n\n```md\n# Before\n\n\u003ch1 id=\"after\"\u003eAfter\u003c/h1\u003e\n```\n\nHowver, you won't need to generate these slugs in your app code again if you plan on using anchor\ntags. The data that the [React API](#react-api) returns contains headings and slug data for any\ngiven markdown page.\n\n## Plugin Options\n\n### `location` (path to source directory)\n\nThe plugin will scan the given `location` folder directory for\n`.md` files which will be added to `react-static` as individual pages.\nThe directories the markdown file is located in and the filename\nitself will be taken into account when adding routes.\n\nThe search itself starts from the `react-static` root that is\nconfigured in `config.paths.root` (which defaults to the current\nworking directory).\n\nFor instance, if location is set to `./docs` and the given list of\nfiles is the following:\n\n```\n|- docs\n   |- getting-started.md\n   |- basics\n      |- installation.md\n   |- advanced\n      |- README.md\n      |- api.md\n```\n\nThe output of routes will be:\n\n- `/getting-started`\n- `/basics/installation`\n- `/advanced` (index route)\n- `/api`\n\nAny file that is named `README.md` or `index.md` (case-insensitive) will\nbe considered an index route. So in the example above `./docs/advanced/README.md`\nbecame `/advanced` instead of `/advanced/readme`.\n\n### `pathPrefix` (base path prefix for routes)\n\nIf this option is set, all routes will be prefixed with what you pass\nto this option. For instance, setting it to `docs` will turn `/getting-started`\nto `/docs/getting-started`.\n\n### `template` (the React template component path)\n\nLike with routes in `react-static`'s `getRoutes`, you'll likely want to wrap\nyour markdown content in React components. This may be done by pointing\n`template` at your template component, e.g. `./src/components/template.js`.\n\nWhen rendered the component will receive the markdown content as JSX, the\ncontent will be passed as the `children` prop.\n\nAn example for a component may look like the following:\n\n```js\n// ./src/components/template.js\nexport default ({ children }) =\u003e (\n  \u003cmain\u003e\n    {children}\n  \u003c/main\u003e\n);\n```\n\n### `remarkPlugins` (a list of remark plugins)\n\nYour markdown files will be parsed using [remark](https://github.com/remarkjs/remark)\nbefore being converted to JSX on the client-side. You may pass more remark plugins\nthat your markdown will be run through during build time.\n\n```\n{\n  remarkPlugins: [\n    [require('remark-emoji'), { padSpaceAfter: true }]\n  ]\n}\n```\n\n### `order` (override the order of pages)\n\nThis may be used to override the order of some pages, which is useful for folders that\nneed sorting, but don't have index files (`README.md` or `index.md`).\n\nThe `order` config can be set to an object of `routeName` to a number, where the route's\nname is either a folder name or a filename.\n\nSince by default the order is alphabetic, if you have two folders, one named `basics/` and one\nnamed `advanced/`, you can swap their order as so:\n\n```js\n{\n  order: {\n    basics: 0,\n    advanced: 1,\n  }\n}\n```\n\n## React API\n\n### Hooks\n\nThis plugin provides two hooks `useMarkdownPage` and `useMarkdownTree`. The former returns\ninformation about the current page's markdown data and the latter returns a nested tree of\nall markdown pages.\n\nThe `useMarkdownPage` hook is available as long as you are on any of the markdown page, `useMarkdownTree` is available in any react-static page.\n\n\n```\nuseMarkdownPage()\n// =\u003e Page\n\nuseMarkdownTree()\n// =\u003e { ...Page, key: string, children: Page[] }\n```\n\nAs shown above, the tree version of the hook returns additional data apart from the common\n`Page` data, which also contains a `key` — the node's directory or filename — and children — the\nchild `Page`s or nodes.\n\nA `Page` is an object that contains more information about the markdown file. Specifically it'll\ncontain:\n\n- `path`: The route to the page, including the `pathPrefix` (if any has been set)\n- `originalPath`: The original path to the markdown file (which is useful as a unique key)\n- `frontmatter`: The JSON object of frontmatter data (*normalized)\n- `headings`: A list of all `h1`, `h2`, and `h3` headings in the markdown file\n\nThe `frontmatter` data is normalised. This means that when your markdown file doesn't have any\nfrontmatter data it'll still be provided, and when you left out `frontmatter.title` it will default\nto the page's first `h1` heading.\n\nThe `headings` array contains all `h1`, `h2`, and `h3` headings as objects. These objects have\na `value` property (the stringified content of the heading), a `slug` property (the slugified\ncontent of the heading), and a depth property (`1 | 2 | 3` depending on the level of the heading.)\n\n### Adding an MDX Provider\n\nThe JSX that the markdown content is rendered as internally uses\n[`@mdx-js/react`](https://www.npmjs.com/package/@mdx-js/react). By default it will render out\nas normal HTML-ified markdown content. However, it's possible to use the `MDXProvider` from\n`@mdx-js/react` to modify the output.\n\n[Read more about the `MDXProvider` in the MDX guides.](https://mdxjs.com/guides)\n\n## Maintenance Status\n\n**Experimental:** This project is quite new. We're not sure what our ongoing maintenance plan for this project will be. Bug reports, feature requests and pull requests are welcome. If you like this project, let us know!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitten%2Freact-static-plugin-md-pages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitten%2Freact-static-plugin-md-pages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitten%2Freact-static-plugin-md-pages/lists"}