{"id":22917166,"url":"https://github.com/dalbitresb12/markdown-docs","last_synced_at":"2025-04-01T12:45:22.989Z","repository":{"id":192307172,"uuid":"686459176","full_name":"dalbitresb12/markdown-docs","owner":"dalbitresb12","description":"Markdown documentation rendering system, using markedpp and markdown-it","archived":false,"fork":false,"pushed_at":"2023-09-10T05:28:23.000Z","size":1326,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-02-07T07:42:09.093Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/dalbitresb12.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,"governance":null}},"created_at":"2023-09-02T21:32:49.000Z","updated_at":"2023-09-06T05:01:50.000Z","dependencies_parsed_at":"2023-09-06T04:25:27.013Z","dependency_job_id":"ed6b3b2f-468c-4c5a-8dcb-02d42822d379","html_url":"https://github.com/dalbitresb12/markdown-docs","commit_stats":null,"previous_names":["nexgeniusupc/plantguard-docs","dalbitresb12/markdown-docs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalbitresb12%2Fmarkdown-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalbitresb12%2Fmarkdown-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalbitresb12%2Fmarkdown-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dalbitresb12%2Fmarkdown-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dalbitresb12","download_url":"https://codeload.github.com/dalbitresb12/markdown-docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246642302,"owners_count":20810568,"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-12-14T06:16:45.815Z","updated_at":"2025-04-01T12:45:22.970Z","avatar_url":"https://github.com/dalbitresb12.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Markdown Documentation\n\nWrite documentation using Markdown, preview as HTML with live reload and render as PDF. Version control your document with Git.\n\n## Why?\n\nThere's probably a lot of easier ways to do this. I just wanted to doing this in my own way. I also needed this for a project at uni.\n\n## Requirements\n\n- [Node.js](https://nodejs.org/en) (LTS, only tested with 18).\n  - **Recommended:** install using a version manager like [nvm](https://github.com/nvm-sh/nvm) or [nvm-windows](https://github.com/coreybutler/nvm-windows).\n- [Yarn v2](https://yarnpkg.com/)\n  - **Recommended:** enable corepack to automatically install Yarn: `corepack enable` on any terminal.\n\n## Quick start\n\nThere's two ways you can start using this for your own documents.\n\n### The recommended way\n\nCreate a [duplicate of the repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository), then add this repository as the upstream remote so that you can pull and merge improvements and features made to the project.\n\n```sh\n# Add the upstream remote to your local copy of the repository\ngit remote add upstream https://github.com/dalbitresb12/markdown-docs.git\n# Pull and merge the changes from the upstream\ngit pull upstream main\n# Push the resulting commits to your repository\ngit push origin main\n```\n\nAnytime you want to pull the latest changes from upstream, you will have to run the **last 2 commands**. You may have to run the first command as well if you delete the upstream remote, use, delete and clone again another copy of your repo where you configured the upstream initially.\n\n### Forking\n\nJust click on the fork button at the top of the page. This will allow you to quickly start writing documentation, but PRs made in your repository will, by default, be directed to the upstream repository (this one). There's **no way to change this behavior** until GitHub makes it configurable.\n\n\u003e If you already forked the repository but want to move to using [the recommended way](#the-recommended-way), you can [request GitHub support to unlink your repository](https://stackoverflow.com/a/16052845/15040387) from this one. This will remove all the downsides of using a fork while keeping all the issues, PRs and commit history.\n\n## Installing modules\n\nJust run `yarn` on the workspace directory.\n\n### Execution Policy and PowerShell\n\nIf you get any errors about an Execution Policy while trying to run any of the scripts provided in PowerShell, run the following command:\n\n```pwsh\nPS\u003e Set-ExecutionPolicy -ExecutionPolicy RemoteSigned\nExecution Policy Change\nThe execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose you to the security risks described in the about_Execution_Policies help topic at\nhttps://go.microsoft.com/fwlink/?LinkID=135170. Do you want to change the execution policy?\n[Y] Yes  [N] No  [S] Suspend  [?] Help (default is \"Y\"): Y\n```\n\n## Generating document\n\nRun the following command:\n\n```sh\n# If you want to run a one-off render\nyarn render\n# If you want to watch for changes and re-render\nyarn watch\n```\n\n### Previewing\n\nCurrently, there's no integrated server with live reload. There's plans for an integrated server, but on the meantime please use Ritwick Dey's [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) extension.\n\nThe repository already includes the configuration necessary to use this extension correctly. Just click on the \"Go Live\" button on the status bar (the bottom bar).\n\n### PDF generation\n\nCurrently, there's no automatic generation of PDF. You can manually render the PDF by opening the preview server on any browser and using \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003eP\u003c/kbd\u003e.\n\n## Writing documentation\n\nThe entrypoint for the renderer is [`docs/index.md`](docs/index.md). This file will be preprocessed with [markedpp](https://www.npmjs.com/package/markedpp). Also, if it has a front matter, it will be parsed by [gray-matter](https://www.npmjs.com/package/gray-matter).\n\nThe Markdown syntax chosen is MultiMarkdown 6, parsed by the [markdown-it](https://www.npmjs.com/package/markdown-it) and [markdown-it-multimd-table](https://www.npmjs.com/package/markdown-it-multimd-table). This syntax allows us to make better tables. You can check the [user guide](https://fletcher.github.io/MultiMarkdown-6/) or the [cheatsheet](https://rawgit.com/fletcher/MultiMarkdown-6-Syntax-Guide/master/index.html) for more info on how to make complex tables.\n\n\u003e There might be some differences with how markdown-it-multimd-table parses the file compared to the original multimarkdown binary.\n\n### Front Matter\n\nThe front matter is only parsed for the entrypoint file.\n\n```yaml\n---\ntitle: Document\nlang: en\n---\n```\n\nIn the [rendered template](src/templates/markdown-template.hbs):\n\n- `title` will be used for the header title element: `\u003ctitle\u003e{{title}}\u003c/title\u003e`.\n- `lang` will be used for the `html` tag attribute with the same name: `\u003chtml lang=\"{{lang}}\"\u003e...\u003c/html\u003e`\n\n### Inserting table of contents\n\nYou can use any of the supported methods of [markdown-it-toc-done-right](https://www.npmjs.com/package/markdown-it-toc-done-right) to insert an automatic table of contents from the headers detected in the document. For example:\n\n```markdown\n## Table of contents\n\n${toc}\n```\n\n### Including files\n\nYou can include any file in the `docs/` directory by using the following syntax:\n\n```markdown\n!include (file.ext)\n```\n\nThis can be used to include other Markdown files to the entrypoint file, allowing you to separate your content into multiple files.\n\nThis can also be used to include any text file, which can be useful to include examples for code blocks. For example:\n\n\u003cdetails\u003e\n\u003csummary\u003e\nexample.js\n\u003c/summary\u003e\n\n```javascript\nconsole.log(\"Hello world\");\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\nindex.md\n\u003c/summary\u003e\n\n\u003e You can safely ignore the `// prettier-ignore` line, it is just needed to show the example correctly in this file.\n\n````markdown\n```javascript\n// prettier-ignore\n!include (example.js);\n```\n````\n\n\u003c/details\u003e\n\nThis will be preprocessed to the following Markdown document before rendering to HTML:\n\n````markdown\n```javascript\nconsole.log(\"Hello world\");\n```\n````\n\n### Static files\n\nAny images or other static files you want to include in your document must go on the `docs/static/` folder. This folder will get symlinked (or junctioned in Windows systems) to the `output/` folder so that the resulting HTML file can access it.\n\nFor example, the following document:\n\n```markdown\n![Alt text](static/image.png \"Title\")\n```\n\nWill render as:\n\n```html\n\u003cimg src=\"static/image.png\" alt=\"Alt text\" title=\"Title\" /\u003e\n```\n\n### Inserting page breaks\n\n```markdown\n{.page-break}\n```\n\nThis will create an empty element with the class `.page-break`, as follows:\n\n```html\n\u003cp class=\"page-break\"\u003e\u003c/p\u003e\n```\n\nThis element is setup to force a page break on the printed PDF file. It **will not** be shown in the HTML preview.\n\n### Styling the document\n\nThe styles used by default are used in the following order:\n\n- A modified version of the [Visual Studio Code light theme stylesheet](https://github.com/microsoft/vscode/blob/main/extensions/markdown-language-features/media/markdown.css) for the preview window.\n- A modified version of the [stylesheet](https://github.com/yzane/vscode-markdown-pdf/blob/master/styles/markdown-pdf.css) used by [Yzane's Markdown PDF Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=yzane.markdown-pdf).\n- A modified version of the [printing styles](https://github.com/h5bp/html5-boilerplate/blob/72cdf1e96c6506c76c51e53abc1f2bd224776649/css/main.css#L234-L304) used by [HTML5 Boilerplate template](https://github.com/h5bp/html5-boilerplate/).\n- A modified version of highlight.js [Visual Studio light theme](https://github.com/highlightjs/highlight.js/blob/main/src/styles/vs.css).\n\n#### Custom styles\n\nIf you need to create custom styles for your document, you can include them in the file located at [`src/css/custom.css`](src/css/custom.css). This file will be loaded last so that you can override any of the base stylesheets.\n\nTo use your custom styles in your Markdown files, check the documentation of the [markdown-it-attrs](https://www.npmjs.com/package/markdown-it-attrs) plugin.\n\n### Loaded plugins for markdown-it\n\nIn order of execution:\n\n- [markdown-it-replace-link](https://www.npmjs.com/package/markdown-it-replace-link)\n- [markdown-it-anchor](https://www.npmjs.com/package/markdown-it-anchor)\n- [markdown-it-toc-done-right](https://www.npmjs.com/package/markdown-it-toc-done-right)\n- [markdown-it-multimd-table](https://www.npmjs.com/package/markdown-it-multimd-table)\n- [markdown-it-highlightjs](https://www.npmjs.com/package/markdown-it-highlightjs)\n- [markdown-it-attrs](https://www.npmjs.com/package/markdown-it-attrs)\n\n### Template\n\nThe [template](src/templates/markdown-template.hbs) rendering is handled by [Handlebars](https://www.npmjs.com/package/handlebars).\n\n### Code blocks\n\nSyntax highlighting for code blocks is handled automatically by [highlight.js](https://www.npmjs.com/package/highlight.js). It has all the common languages loaded.\n\n### Friendly URLs\n\nSlugs for the table of contents and anchors are handled by [@sindresorhus/slugify](https://www.npmjs.com/package/@sindresorhus/slugify).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalbitresb12%2Fmarkdown-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdalbitresb12%2Fmarkdown-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdalbitresb12%2Fmarkdown-docs/lists"}