{"id":21497194,"url":"https://github.com/financial-times/express-markdown-pages","last_synced_at":"2025-07-15T19:33:27.177Z","repository":{"id":39636506,"uuid":"319923142","full_name":"Financial-Times/express-markdown-pages","owner":"Financial-Times","description":"An Express middleware that transforms plain text files into dynamic pages and fits right into your existing app.","archived":false,"fork":false,"pushed_at":"2023-12-06T17:26:36.000Z","size":2355,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-04-08T16:48:02.344Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Financial-Times.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-09T10:38:25.000Z","updated_at":"2024-07-26T15:48:20.338Z","dependencies_parsed_at":"2024-07-26T15:47:50.824Z","dependency_job_id":"b672e223-2f06-4cc0-9c5b-5d22841e2215","html_url":"https://github.com/Financial-Times/express-markdown-pages","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Financial-Times%2Fexpress-markdown-pages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Financial-Times%2Fexpress-markdown-pages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Financial-Times%2Fexpress-markdown-pages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Financial-Times%2Fexpress-markdown-pages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Financial-Times","download_url":"https://codeload.github.com/Financial-Times/express-markdown-pages/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226065797,"owners_count":17568268,"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-11-23T16:22:06.548Z","updated_at":"2024-11-23T16:22:07.341Z","avatar_url":"https://github.com/Financial-Times.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @financial-times/express-markdown-pages\n\n[![CircleCI](https://img.shields.io/circleci/project/github/Financial-Times/express-markdown-pages/main.svg)](https://circleci.com/gh/Financial-Times/express-markdown-pages) [![NPM version](https://img.shields.io/npm/v/@financial-times/express-markdown-pages.svg)](https://www.npmjs.com/package/@financial-times/express-markdown-pages)\n\nAn Express middleware that transforms plain text files into dynamic pages and fits right into your existing app.\n\n```js\nconst { MarkdownPages } = require('@financial-times/express-markdown-pages');\n\nconst markdownPages = new MarkdownPages();\n\napp.get('/*', markdownPages.middleware, (request, response) =\u003e {\n\tconst html = myTemplate(response.locals.markdownPages);\n\tresponse.send(html);\n});\n```\n\n[1]: https://github.com/Financial-Times/biz-ops-api#api\n\n## Installation\n\nThis is package for [Node.js] and is available through the [npm] registry. Node 20 or higher is required.\n\nInstallation is done using the [npm install] command:\n\n```bash\nnpm install -S @financial-times/express-markdown-pages\n```\n\n[node.js]: https://nodejs.org/\n[npm]: http://npmjs.com/\n[npm install]: https://docs.npmjs.com/getting-started/installing-npm-packages-locally\n\n## Features\n\n-   Fits right into your existing Express app, how you render the output is up to you!\n-   Finds and transforms Markdown files into HTML with Origami compatible output.\n-   Author content that works in your editor, on GitHub, and on your website.\n-   Generates hierarchical navigation and user-friendly URLs.\n-   Supports taxonomies to dynamically group and filter content.\n-   Include images alongside your Markdown content, they'll work too.\n\n## Getting started\n\nStart by creating a new instance of `MarkdownPages` and provide the appropriate [options](#options) for your app:\n\n```js\nconst { MarkdownPages } = require('@financial-times/express-markdown-pages');\n\nconst markdownPages = new MarkdownPages({\n\tsource: './content',\n\tpathPrefix: '/docs',\n});\n```\n\nNext, add a new route to your app to serve your Markdown pages from, please note this must end with an asterisk (`*`) so that Express knows to route all requests to URLs beginning with this path through the `MarkdownPages` middleware:\n\n```js\napp.get('/docs*');\n```\n\nNext, add the `MarkdownPages` middleware to the route you just added:\n\n```js\napp.get('/docs*', markdownPages.middleware);\n```\n\nNext, add a final [route handler] function. This function can use [the data](#page-data) added by the middleware to render your pages. Please note, if a page can't be found, or the incoming request is for an image file, then this function will not be called:\n\n```js\napp.get('/docs*', markdownPages.middleware, (request, response) =\u003e {\n\tresponse.send(response.locals.markdownPages);\n});\n```\n\nFinally, we recommend initialising `MarkdownPages` on app startup. This is not strictly necessary but it will help you to spot any errors with your content:\n\n```js\ntry {\n\tawait markdownPages.init();\n\n\tapp.listen(PORT, () =\u003e {\n\t\tconsole.log(`App listening on http://localhost:${PORT}`);\n\t});\n} catch (error) {\n\tconsole.error('The app failed to start: ', error);\n\tprocess.exit(1);\n}\n```\n\nNow you're up and running you can get on with using [the data](#page-data) in your templates or carry on to the [documentation](docs/index.md) for more examples.\n\n[route handler]: https://expressjs.com/en/guide/routing.html#route-handlers\n\n### Options\n\nSee the [JSDoc type definitions](docs/jsdoc.md#Options) for more information about configuration options.\n\n### Debugging\n\nThis package implements [debug] to provide detailed logs. You can enable these by setting the `DEBUG` environment variable:\n\n```shell\nDEBUG=express:markdownPages node app.js\n```\n\n[debug]: https://www.npmjs.com/package/debug\n\n### Page data\n\nThe middleware provided by this package will append a `markdownPages` property to the [`response.locals` object](https://expressjs.com/en/4x/api.html#res.locals) when a page matching the request is found. This object includes the content for the requested page and navigation hierarchy, and for [index pages](docs/writing-content.md#index-pages) it will also include any information about taxonomies and tags used by child pages.\n\nSee the [JSDoc type definitions](docs/jsdoc.md#PageData) for more information about page data.\n\n### Writing content\n\nSee the [writing content guide](docs/writing-content.md) for more information about the syntax and conventions for authoring content compatible with this package.\n\n## Screenshots\n\n| In VSCode                                          | On GitHub                                          | Rendered on a website                                        |\n| -------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------ |\n| ![A page viewed in VSCode](docs/images/vscode.png) | ![A page viewed on GitHub](docs/images/github.png) | ![A page viewed in the web browser](docs/images/website.png) |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinancial-times%2Fexpress-markdown-pages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffinancial-times%2Fexpress-markdown-pages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinancial-times%2Fexpress-markdown-pages/lists"}