{"id":18376925,"url":"https://github.com/bbc/morty-docs","last_synced_at":"2025-04-06T20:31:47.809Z","repository":{"id":35323876,"uuid":"216591465","full_name":"bbc/morty-docs","owner":"bbc","description":"Generate a static website from markdown files","archived":false,"fork":false,"pushed_at":"2024-11-26T16:53:58.000Z","size":2345,"stargazers_count":22,"open_issues_count":5,"forks_count":9,"subscribers_count":50,"default_branch":"main","last_synced_at":"2025-01-12T09:51:32.951Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbc.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-21T14:39:43.000Z","updated_at":"2024-11-26T16:54:02.000Z","dependencies_parsed_at":"2024-09-17T13:43:30.446Z","dependency_job_id":"48df4faa-3132-4cf0-9e27-90895dff2aa5","html_url":"https://github.com/bbc/morty-docs","commit_stats":null,"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fmorty-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fmorty-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fmorty-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fmorty-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbc","download_url":"https://codeload.github.com/bbc/morty-docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247547634,"owners_count":20956589,"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-06T00:25:27.755Z","updated_at":"2025-04-06T20:31:47.803Z","avatar_url":"https://github.com/bbc.png","language":"JavaScript","readme":"# Morty Docs\n\n## Overview\n\nMorty Docs is a library to enable documentation to be generated as a static\nwebsite, to allow users to consume the content in an easily accessible format.\nIt takes an array of markdown and/or asciidoc files and creates a static website.\n\nMorty is specifically aimed at requiring little to no change in the markdown/asciidoc files.\n\nIn the BBC we have a large amount of git repositories which often have markdown documentation within them, they don't follow a consistent structure and their content structure can also be wildly different. We wanted a way to publish these with the minimal amount of effort from teams, Morty Docs is what we use to solve this problem.\n\n## Example site made with Morty-Docs\n\nThe documentation located [here](https://github.com/bbc/lrud) has been converted to a site using morty-docs, the converted docs can be viewed [here](https://bbc.github.io/morty-docs/).\n\n## Why use Morty Docs over other static site generation?\n\nUse Morty Docs when you already have some markdown/asciidoc files in a directory structure which you want to publish.\n\nMorty Docs was specifically created to publish already existing markdown files without having to change the contents of those files.\nIt does not use specific directory structures or meta data about the files.\nMorty infers the navigation by the directory structure of the files and can be used with no configuration at all.\nPlain simple markdown files go in, a html site comes out.\n\nIf you do want to be able to have more control over the website which is published and are happy to change your files and structure you might want to pick a more complex static site generator.\n\n## Try it locally\n\n```bash\ngit clone git@github.com:bbc/morty-docs.git\ncd morty-docs\nnpm ci\nnpm start # starts local server running Morty Docs\n```\n\nOpen http://localhost:8080/ in your browser\n\nMorty Docs will generate a website listing an HTML page for each markdown file in the `/default-md-files` directory\n\nTo try it with markdown files from a custom directory\n```bash\nmortyPath=/absolute/path/to/custom/directory npm start\n```\n\n## Use as a library\n\n### Install\n\n`npm install --save @bbc/morty-docs`\n\n### Require\n\n```javascript\nconst { generateTransformInput, transform } = require('@bbc/morty-docs')\n```\n\n### Typical use\n\n```javascript\nconst inputObjs = await generateTransformInput('a/folder/with/markdown-files')\n\nconst outputObjs = transform(inputObjs,{ contentTitle: 'My Docs', basePath: '/path/my/docs/are/hosted/under' })\n```\n\n- `transform()` can be used alone, but if your files are in a local\ndirectory the `generateTransformInput()` function is a convenience\n- the 2nd argument to `transform()` can *optionally* be used to provide a Title\nthat is displayed on the generated index pages and the base path below which your files will be served (this required to make markdown links starting with `/` work).\n\n- `outputObjs` will be an array of objects like this:\n\n``` javascript\n[\n  {\n    relativePath: 'path/to/file',\n    raw: \u003cstring\u003e | \u003cBuffer\u003e\n  },\n  ...\n]\n```\n\nwhere value for raw is either generated HTML **or** input that was passed\nthrough because it is not markdown or asciidoc e.g. images\n\n## Things to Consider\n\n### Index file generation\n\nMorty will automatically generate an `index.html` file for any directory that\ncontains markdown or asciidoc files (or has descendants that contain these\nfiles). This file contains links to any documentation files or subdirectories\nthe directory contains. The generation will be skipped for any directory that\nalready contains an `index.md`, `index.asciidoc`, `index.adoc` or `index.asc` file.\n\n### File \u0026 Directory Ordering\n\nThese are sorted lexically (0-9 \u003c a-z\u003e).\n\nThere is an additional sort.\nIf you want your documents to be sorted reverse chronologically, use the date as a prefix to the file name in the format YYYY-MM-DD e.g. `19-11-2019-some-document`. These will then be placed first above the regular sort.\n\n## Example Architecture\n\nBelow is an example architecture diagram showing how you could integrate morty-docs with GitHub and AWS S3 to generate static websites for all of an organisation's repositories\n\n![Example Architecture Diagram for integrating Morty-Docs with GitHub](docs/morty-architecture-diagram.png)\n\n## Known issues\n\nWe are currently unaware of any issues with morty-docs - if you find an issue\nplease raise it using our Contribution Guide.\n\n## Why Call it Morty Docs?\n\nMorty Docs originated from an internal project specifically created to publish\nour Post Mortem documents which we were writing in Markdown storing in GitHub.\nThis project was called PostMortemer. We then realised this would be useful for\n_any_ Markdown documents! So we made it more generic and called it Morty Docs!\n\n## Contributing\n\nThanks for wanting to improve the project!\n\nBefore contributing back, please familiarise yourself with a few things\nwe mention below.\n\n### Can I contribute?\n\nYes.  Contributions are accepted based on the merit of the contribution,\nnot on the basis of who they are from.\n\nWe welcome contributions from everyone.\n\nPlease respect each other.\n\n## How to contribute\n\nSteps:\n\n- fork the repo\n- implement your fix or feature - with test coverage :-)\n- raise a [PR](https://github.com/bbc/morty-docs/pulls)\n- this repo now uses github actions for automated Pull Request checking \u0026 Publishing\n  - n.b. first-time contributors require approval to run github actions\n  (so your PR checker should fail to run initially)\n- use ['Pull Request Checks' github action](https://github.com/bbc/morty-docs/actions/workflows/pull-requests.yml) to\nsee if the PR checker is passing\n\n### Maintainers only\n\n- merge PR (or suggest changes)\n- after merge\n  - use `npm version (major|minor|patch)`\n  - the tag created above causes\n  ['Node.js Package' github action](https://github.com/bbc/morty-docs/actions/workflows/npm-publish.yml) to run.\n  Wait for this to complete.\n  - verify the new version on [NPM](https://www.npmjs.com/package/@bbc/morty-docs)\n\n### Adding an issue\n\nIf you spot an issue or just want to raise one please use the issue template.\n\n### Contact us!\n\nIt's always great to hear from people who are interested and\nusing morty-docs.\n\nThe best way to do this is to open an issue.  Please note, that where a\nfeature is requested, but we can't add *right now*, will result in us\nadding a TODO label to it. We'll come back to it when we can or someone\nout there might implement it.\n\n### Incorporating Contributions\n\nWe will always accept contributions. We endeavour to ensure that they\nfit with the existing code base.\n\nIf we alter the contribution we will let you know clearly why. We're\nactually more likely to also let you know what we think would be\nnecessary changes in order to accept your contribution.\n\nEither way, that doesn't stop you using your change nor stop you releasing\nyour version.  It just means it doesn't fit with the project as we see it\nat this time.\n\n### Proposing Changes\n\nPlease open an issue.  Then fork the project.  Make your changes in your\nclone fork, and create a pull request, referencing the issue. We'll then\ndiscuss the pull request in the issue.\n\nWe would expect code quality to be at least as good if not better than\nthe code quality of the project at the time you make your contribution.\nAfter all, we all hope to leave things better than we find them!\n\n© BBC 2024\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Fmorty-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbc%2Fmorty-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Fmorty-docs/lists"}