{"id":16774205,"url":"https://github.com/dragonwocky/documentative","last_synced_at":"2025-04-10T20:06:38.374Z","repository":{"id":47891765,"uuid":"244077596","full_name":"dragonwocky/documentative","owner":"dragonwocky","description":"a tool for precompiling docs from markdown","archived":false,"fork":false,"pushed_at":"2021-10-07T10:00:40.000Z","size":749,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T17:52:37.632Z","etag":null,"topics":["documentation-generator","markdown","navigation","precompile"],"latest_commit_sha":null,"homepage":"https://dragonwocky.me/documentative","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/dragonwocky.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-03-01T03:05:31.000Z","updated_at":"2023-05-17T22:28:52.000Z","dependencies_parsed_at":"2022-08-26T13:41:25.729Z","dependency_job_id":null,"html_url":"https://github.com/dragonwocky/documentative","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonwocky%2Fdocumentative","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonwocky%2Fdocumentative/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonwocky%2Fdocumentative/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonwocky%2Fdocumentative/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dragonwocky","download_url":"https://codeload.github.com/dragonwocky/documentative/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248288340,"owners_count":21078900,"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":["documentation-generator","markdown","navigation","precompile"],"created_at":"2024-10-13T06:48:25.047Z","updated_at":"2025-04-10T20:06:38.356Z","avatar_url":"https://github.com/dragonwocky.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# documentative\n\na tool for precompiling docs from markdown\n\n[![npm](https://badgen.net/npm/v/documentative?color=blue)](https://npmjs.com/package/documentative)\n[![install size](https://badgen.net/packagephobia/install/documentative?color=pink)](https://packagephobia.now.sh/result?p=documentative)\n[![downloads](https://badgen.net/npm/dt/documentative?color=green)](https://npmjs.com/package/documentative)\n[![discord](https://badgen.net/badge/icon/discord?icon=discord\u0026label\u0026color=purple)](https://discord.gg/g39aNQe)\n[![license](https://badgen.net/npm/license/documentative?color=b20000)](https://choosealicense.com/licenses/mit/)\n\n## what is this? why use it?\n\nthere are a lot of tools out there for publishing websites and for generating documentation.\nsome are really powerful - even to the extend of processing code and building docs straight from that.\nsometimes it's just simpler to write some markdown and publish it as a static site on github pages.\n\ni was doing that a lot: and since i was writing markdown and then also manually building a matching\nwebsite, i was spending nearly as much time on that as i was on coding the project itself. i had a\nreasonably solid template i was using already, so i did what leads many people to publishing things\nlike this: i thought to myself 'how can i automate this?'\n\ndocumentative cuts out half the work - you write the markdown; it builds you a responsive, modern website.\n\n**demo:** [https://dragonwocky.me/documentative/](https://dragonwocky.me/documentative/)\n\n_features of a built site include..._\n\n- a responsive layout! mobile support is robust, with the sidebar transforming into\n  a hamburger-triggered menu.\n- light/dark mode that respects the user's system mode (with the capability to display a different\n  icon depending on the mode).\n- in-page navigation via #IDs (with a sidebar that scrolls to match the reader location), allowing\n  for keeping your place on the page when you reload or linking to a specific section.\n- social-media embed friendly.\n- \\+ y'know, like, being a configurably built site - you pick a primary colour, you define a footer,\n  you choose which files are served or precompiled... etc.\n\n## usage\n\nthis package is available from the npm package registry.\n\n```bash\nnpm i -s documentative\n```\n\n```js\nconst docs = require('documentative');\n```\n\n#### to build/precompile to a directory\n\n```js\ndocs.build(inputdir, outputdir, options);\n// returns a promise: resolves to true\n```\n\n| argument    | type   | value                    |\n| ----------- | ------ | ------------------------ |\n| `inputdir`  | string | e.g. `'pages'`           |\n| `outputdir` | string | e.g. `'build'`           |\n| `options`   | object | see [#options](#options) |\n\nif you wish your `inputdir` and `outputdir` to be the same,\nthat works too - just enable the overwrite option (see [#options](#options)).\n\n```js\ndocs.build('.', '.', { overwrite: true });\n```\n\n#### to serve the directory from a local http server\n\n```js\ndocs.serve(inputdir, port, options);\n// returns a promise: resolves to the started http server\n```\n\n| argument   | type   | value                    |\n| ---------- | ------ | ------------------------ |\n| `inputdir` | string | e.g. `'pages'`           |\n| `port`     | number | e.g. `8080`              |\n| `options`  | object | see [#options](#options) |\n\n\u003e ❗ not recommended unless for testing purposes\n\u003e \\- especially if serving a larger directory,\n\u003e as it will re-read the entire directory for\n\u003e every file serve.\n\n## cli\n\nif this is your preferred method of use, it is recommended to install via `npm i -g documentative`.\n\n```\nusage:\n\n  \u003e documentative-build \u003cinputdir\u003e \u003coutputdir\u003e\n  e.g. documentative-build pages build\n\n  \u003e documentative-serve \u003cinputdir\u003e [--port, -p PORT]\n  e.g. documentative-serve pages -p 3000\n\noptions:\n  --help, -h   show this message\n  --port, -p   set the HTTP server port used by documentative-serve\n    (default: 8080)\n\n** to configure the process, place configuration options into\n   \u003cinputdir\u003e/docs.json\n```\n\n\u003e ℹ️ the `\u003cinputdir\u003e/docs.json` file will be added\n\u003e to the exclude list (see [#options](#options)).\n\n## writing a page\n\npages are written in github flavoured markdown.\n\nit is recommended to start every page with a `# h1`, as that is what is used\nfor the sidebar table-of-contents documentative generates.\n\nin order to maintain viability of pages as both markdown and html, any local markdown page\nlinks are changed to match page src -\u003e output. e.g. a link written as `[link](README.md)`\nmay transformed to `\u003ca href='index.html'\u003elink\u003c/a\u003e`.\n\ncheck out [the styling guide](styling-guide.md) for ways to further customise what comes out.\n\n## options\n\n```js\n{\n  title: string, // default: 'documentative'\n  primary: string/colour, // default: '#712c9c\n  git: string/url,\n  footer: string,\n    // default: '© 2020 someone, under the [MIT license](https://choosealicense.com/licenses/mit/).'\n  card: {\n    description: string,\n    url: string/url\n  },\n  icon: {\n    light: string/filepath,\n    dark: string/filepath\n  },\n  overwrite: boolean, // default: false\n  exclude: [strings/filepaths],\n  ignoredotfiles: boolean, // default: true\n  nav: []\n}\n```\n\n#### git + footer\n\nmarkdown can be used within the footer.\n\nthe `git` property defines the url to your inputdir on github or a similar site, excluding the file itself.\nfor github repos, the url must be `https://github.com/user/repo/blob/\u003cbranch\u003e/[folder/]`.\nfor gitlab, it must be `https://gitlab.com/user/repo/-/blob/\u003cbranch\u003e/[folder/]`.\n\ne.g. your `.md` files are in a folder called `docs` @ the `master` branch of the repo `https://github.com/myname/project/`.\nyou would set the `git` property to `https://github.com/myname/project/blob/master/nav`.\n\nthen, if within the footer you wish to link to the hosted `.md` of the page, simply set it to:\n`\"[Edit on Github](__git__)\"`. the `__git__` will be replaced by the config definition + the page source.\nfor the example above, when visiting `page.html`, the footer would link to `https://github.com/myname/project/blob/master/nav/page.md`.\n\nif you wish to completely hide the `footer`,\nsimply set the following:\n\n```js\nfooter: '',\n```\n\n#### card\n\nthe `card` properties are used for the preview embeds/cards created by social media platforms\nwhen linking to your page. the `card.url` should be the canonical base url for your site and must end with a `/`.\n(e.g. `https://example.com/` or `https://dragonwocky.me/documentative/`, but NOT `https://dragonwocky.me/documentative/page.html`)\n\n#### icon\n\nthe light/dark icons will be shown dependent on whether the viewer has light/dark mode enabled.\nif only 1 of the icons is set (either light or dark), that icon will be shown for both modes.\n\n#### overwrite\n\n\u003e ❗ beware of turning on overwrite, as any files copied\n\u003e across from the inputdir will irreversibly overwrite\n\u003e files in the outputdir with conflicting names.\n\n#### exclude\n\nto exclude everything within a folder, end the exclude with `/*` (e.g. `ignorethisdir/*`).\n\n\u003e ℹ️ any files within `node_modules`\n\u003e directories will always be excluded, regardless of\n\u003e inclusion in the above list.\n\n#### ignoredotfiles\n\nif true, will not build/serve any files or folders starting with a `.`.\n\n### the nav: default behaviour\n\n1. all markdown files are listed.\n2. nav entry names are the first header within the `.md`,\n   or the filename.\n3. entries are sorted by alphabetical order,\n   though the `index.md` file is always first.\n4. if there is no `index.md` but there is a `README.md`,\n   it becomes the first in the order and is output as `index.html`.\n5. entries are categorised by directory (a title is added\n   with the name of the directory).\n\n### the nav: custom behaviour\n\n#### defining a title\n\nstrict definition:\n\n```js\n{\n  type: 'title',\n  text: string // e.g. 'this is a title'\n}\n```\n\nshorthand:\n\n```js\nstring,\n// e.g. 'this is a title'\n```\n\n#### defining a page\n\nstrict definition:\n\n```js\n{\n  type: 'page',\n  output: string/filepath, // e.g. 'getting-started.html'\n  src: string/filepath, // e.g. 'tutorial.md'\n}\n```\n\nshorthand:\n\n```js\n[output, src, git],\n// e.g. ['getting-started.html', 'tutorial.md']\n```\n\n\u003e if the src is not a valid/existing file, it will be assumed to be a link.\n\n#### defining a link\n\nstrict definition:\n\n```js\n{\n  type: 'link',\n  text: string, // e.g. github\n  url: string/url // e.g. https://github.com/dragonwocky/documentative/\n}\n```\n\nshorthand:\n\n```js\n[text, url],\n// e.g. ['github', 'https://github.com/dragonwocky/documentative/']\n```\n\n#### example nav\n\nstrict definition:\n\n```js\n[\n  { type: 'page', output: 'getting-started.html', input: 'tutorial.md' },\n  { type: 'title', text: 'resources' },\n  {\n    type: 'link',\n    text: 'github',\n    url: 'https://github.com/dragonwocky/documentative/',\n  },\n];\n```\n\nshorthand:\n\n```js\n[\n  ['getting-started.html', 'tutorial.md'],\n  'resources',\n  ['github', 'https://github.com/dragonwocky/documentative/'],\n];\n```\n\n(these methods can be mixed.)\n\n## output\n\n#### build\n\n1. the output directory is created if it does not already exist.\n2. all assets (non-`.md`) files are copied across as they are.\n3. all markdown files included in the nav are output.\n4. documentative resource files are copied across: `docs.js`,\n   `docs.css` and (only if no icon has been specified in the\n   build/serve options) `light-docs.png` and `dark-docs.png`.\n\n\u003e ❗ note that this means you cannot have any assets with those\n\u003e names, as they will be overriden.\n\n#### serve\n\na http server is created. whenever a request is received:\n\n1. if `docs.js` or `docs.css` are requested, serve them\n   from documentative's resources.\n2. if an icon has been specified and is requested, serve it.\n   otherwise, the icon shall be served as `light-docs.png` or `dark-docs.png`.\n3. if a nav entry of type page and with an output\n   matching the request exists, serve it.\n4. if the file exists in the asset list (all non-`.md` files),\n   serve it.\n5. if a file has still not been served, return a 404 error.\n\n\u003e ❗ note that this means if you have a `.html` file called (e.g.)\n\u003e `getting-started.html` and a `.md` file with its output set to\n\u003e `getting-started.md`, the parsed `.md` will override the `.html` file.\n\n## other details\n\nyes, some of the code blocks on this page end with unnecessary commas. my linter enforces it.\n\ni also have an unhealthy habit of avoiding capital letters. nothing enforces this, i just do it.\n\nthe awesome logo is thanks to [@nathfreder](https://github.com/nathfreder/) :D\n\nif you have any questions, check my website for contact details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdragonwocky%2Fdocumentative","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdragonwocky%2Fdocumentative","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdragonwocky%2Fdocumentative/lists"}