{"id":18441694,"url":"https://github.com/davay42/vitepress-pages","last_synced_at":"2025-10-03T14:06:26.317Z","repository":{"id":41362615,"uuid":"470698505","full_name":"davay42/vitepress-pages","owner":"davay42","description":"Markdown pages structure generator for Vitepress","archived":false,"fork":false,"pushed_at":"2023-07-29T06:05:36.000Z","size":7994,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-09-18T23:13:06.118Z","etag":null,"topics":["markdown","parser","vite","vitepress"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/vitepress-pages","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davay42.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"davay42","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2022-03-16T18:05:45.000Z","updated_at":"2023-06-19T16:34:11.000Z","dependencies_parsed_at":"2023-02-14T13:50:22.170Z","dependency_job_id":null,"html_url":"https://github.com/davay42/vitepress-pages","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davay42%2Fvitepress-pages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davay42%2Fvitepress-pages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davay42%2Fvitepress-pages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davay42%2Fvitepress-pages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davay42","download_url":"https://codeload.github.com/davay42/vitepress-pages/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223296859,"owners_count":17121962,"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":["markdown","parser","vite","vitepress"],"created_at":"2024-11-06T06:39:09.419Z","updated_at":"2025-10-03T14:06:21.274Z","avatar_url":"https://github.com/davay42.png","language":"TypeScript","funding_links":["https://github.com/sponsors/davay42"],"categories":[],"sub_categories":[],"readme":"### File system based routing for [`vitepress`](https://vitepress.vuejs.org/) digital gardening\n\n[`vitepress-pages`](https://www.npmjs.com/package/vitepress-pages) is a [`vite-plugin-pages`](https://github.com/hannoeru/vite-plugin-pages) extension for automatic routes generation out of any `markdown` data collection.\n\n## What does it do?\n\n### In Node\n\n- Scans your project folder structure\n- Traverses all `index.md` files\n- Parses frontmatter\n- Optimizes media files\n- Creates client-side interface for us to use in our\n\n### In browser\n\n- Gives you access to the routes array\n- Recreates hierarchical folder tree structure for navigation and search\n- Generates parents list for any given page\n- Finds previous and next siblings along with the index of current page in the list and the total number of pages in it\n\nTech used:\n\n- [graymatter](https://github.com/jonschlinkert/gray-matter) for parsing markdown files. We copy all the frontmatter, generate excerpt and have a flag for empty content. We don't load all the file contents in order to keep the list light enough even for quite big sites.\n\n  You can force load contents with a flag `type: block` put into your `index.md` frontmatter\n\n- [sharp](https://github.com/lovell/sharp) for image resizing.\n\n## Installation\n\n```bash\nnpm i -D vite-plugin-pages vite-plugin-pages-sitemap\nnpm i vitepress-pages\n```\n\n## Configuration\n\n`vite.config.js`\n\n```js\nimport { defineConfig } from \"vite\";\nimport Pages from \"vite-plugin-pages\";\nimport { extendRoutes } from \"vitepress-pages\";\nimport generateSitemap from \"vite-plugin-pages-sitemap\"; //optional;\n\nexport default defineConfig({\n\tplugins: [\n\t\tPages({\n\t\t\tdirs: [{ dir: \".\", baseRoute: \".\" }],\n\t\t\textensions: [\"md\"],\n\t\t\t...extendRoutes(),\n\t\t\tonRoutesGenerated: (routes) =\u003e\n\t\t\t\tgenerateSitemap({ routes, hostname: \"http://localhost/\" }), //provide a hostname and generate a `sitemap.xml` in the public folder\n\t\t}),\n\t],\n});\n```\n\n## Options\n\nYou can customize the `extendRoutes` call with these options.\n\n```js\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n{\n...extendRoutes({ //these are default options\n        root: path.dirname(fileURLToPath(import.meta.url)),\n        graymatter: { // graymatter options\n          excerpt: true,\n          excerpt_separator: \"\u003c!-- excerpt --\u003e\",\n        },\n        mediaFolder: \"media_files\", // the name of a folder inside your /public/ to put all the optimized images to\n        mediaTypes: { // what frontmatter fields should be considered as images and how should sharp deal with them\n          icon: { width: 300, height: 300, fit: \"inside\" },\n          cover: { size: 1200, height: 800, fit: \"inside\" },\n        },\n      })\n}\n```\n\n## Usage\n\nYou can import the list of all routes from `~pages` anywhere in the app. We provide basic of functions at `vitepress-pages/browser` to navigate them easily.\n\n`composables/pages.js`\n\n```js\nimport routes from \"~pages\"; // all routes list from `vite-plugin-pages`\nimport {\n\tgetPage,\n\tgetPages,\n\tgetParents,\n\tgetSiblings,\n} from \"vitepress-pages/browser\";\n\nconst pages = getPages(routes); // hierarchical structure of the pages\n\nconst usePage = (path) =\u003e getPage(path, routes); // current page data object\nconst useParents = (path) =\u003e getParents(path, routes); // An array of parent routes starting from the root\nconst useSiblings = (path) =\u003e getSiblings(path, routes); // { prev, next, index, total }\n\nexport { routes, pages, usePage, useParents, useSiblings };\n```\n\n## Display\n\nThe last step is to create some [Vue 3](https://vuejs.org) components to display all the data. You can import any of the functions and use them with current (or another) route path.\n\n`\u003cscript setup\u003e`\n\n```js\nimport {\n\tpages,\n\tusePage,\n\tuseSiblings,\n\tuseParents,\n} from \"@theme/composables/pages\";\n\nimport { useRoute } from \"vitepress\";\nconst route = useRoute();\n\nconst page = computed(() =\u003e usePage(route.path));\nconst siblings = computed(() =\u003e useSiblings(route.path));\nconst parents = computed(() =\u003e useParents(route.path));\nconst children = computed(() =\u003e pages[route.path]);\n```\n\n`\u003ctemplate\u003e`\n\nBe creative!\n\n```html\n\u003csection v-for=\"page in pages\" :key=\"page\"\u003e\n\t\u003cimg :src=\"page.cover\" /\u003e\n\t\u003ch2\u003e{{ page.title }}\u003c/h2\u003e\n\t\u003cp\u003e{{ page.subtitle }}\u003c/p\u003e\n\t\u003ch3 v-for=\"child in pages[page.path]\" :key=\"child\"\u003e{{ child.title }}\u003c/h3\u003e\n\u003c/section\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavay42%2Fvitepress-pages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavay42%2Fvitepress-pages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavay42%2Fvitepress-pages/lists"}