{"id":22833196,"url":"https://github.com/oxy2dev/markdoc","last_synced_at":"2025-05-06T20:08:46.675Z","repository":{"id":266922758,"uuid":"899774803","full_name":"OXY2DEV/markdoc","owner":"OXY2DEV","description":"A very simple \"markdown\" to \"vimdoc\" converter.","archived":false,"fork":false,"pushed_at":"2025-04-19T13:51:45.000Z","size":595,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-19T18:06:44.776Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","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/OXY2DEV.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-07T01:48:25.000Z","updated_at":"2025-03-26T09:21:09.000Z","dependencies_parsed_at":"2024-12-07T02:28:57.592Z","dependency_job_id":"e19a69b8-45ee-4d9f-bd0b-042f83b57860","html_url":"https://github.com/OXY2DEV/markdoc","commit_stats":null,"previous_names":["oxy2dev/markdoc"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OXY2DEV%2Fmarkdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OXY2DEV%2Fmarkdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OXY2DEV%2Fmarkdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OXY2DEV%2Fmarkdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OXY2DEV","download_url":"https://codeload.github.com/OXY2DEV/markdoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252761192,"owners_count":21800124,"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-12T21:12:33.421Z","updated_at":"2025-05-06T20:08:46.644Z","avatar_url":"https://github.com/OXY2DEV.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Demo 1](https://github.com/OXY2DEV/markdoc/blob/main/assets/markdoc-1-min.png)\n\n![Demo 2](https://github.com/OXY2DEV/markdoc/blob/main/assets/markdoc-2-min.png)\n\n\u003cp align=\"center\"\u003e✨ markdoc\u003c/p\u003e\n\u003cp align=\"center\"\u003eA feature rich markdown to vimdoc converter for pandoc.\u003c/p\u003e\n\n\u003cMKDocTOC/\u003e\n\n## 🥅 Goals\n\n| Goal                                     | Progress |\n|------------------------------------------|----------|\n| Basic markdown syntax support            | Complete |\n| Basic HTML support                       | Complete |\n| Handling of `\\n` in HTML                 | Complete |\n| Allowing text alignment                  | Complete |\n| Callout support                          | Complete |\n| Wrap for nested elements                 | Complete |\n| Ability to change configuration per file | Complete |\n| Ability to place TOC anywhere            | Complete |\n| Handling LaTeX                           | None     |\n| Handling characters with varying widths  | None     |\n| More syntax support(HTML, Markdown)      | None     |\n\n## 💥 Features\n\n- Config per file, allows configuring `markdoc` using YAML metadata.\n- Tag(s) per heading, allows using Lua patterns to add one or more tags to matching headings. \n- Creating TOCs, allows creating Table of contents via YAML.\n- Callout \u0026 title support, supports callouts(even custom ones) and titles for block quotes.\n- Prettier table rendering, tables can be created with custom borders with text wrapping support.\n- Nesting support, supports nesting of block elements.\n- Base HTML support, supports basic HTML tags.\n- `align=\"\"` support, allows aligning text via HTML.\n\n## 📚 Usage\n\nYou only need the `markdoc.lua` file. So, just copy it to your desired location.\n\nYou can then run it like so,\n\n```shell\npandoc -t path/to/markdoc.lua README.md -o help.txt\n```\n\n\u003e[!TIP]\n\u003e You can store metadata in a separate file too if you like. Then you will do something like this,\n\u003e \n\u003e ```sh\n\u003e # Load the metadata file first\n\u003e pandoc metadata.md README.md -t path/to/markdoc.lua -o help.txt\n\u003e ```\n\n## 💨 Github actions\n\n\u003e[!WARNING]\n\u003e I am not very knowledgable when it comes to GitHub actions, so feel free to do PR(s) to fix issues I missed.\n\n```yml\nname: markdoc\non:\n  push:\n    branches:\n      - main\n\npermissions:\n  contents: write\n\njobs:\n  doc:\n    runs-on: ubuntu-latest\n    name: \"To vimdoc\"\n    steps:\n      - uses: actions/checkout@v2\n        with:\n          ref: ${{ github.heade_ref }}\n      - uses: OXY2DEV/markdoc@main\n        with:\n          config: '{ \"doc/markdoc.txt\": [ \"mREADME.md\", \"README.md\" ] }'\n          help_dirs: '[ \"doc\" ]'\n      - uses: stefanzweifel/git-auto-commit-action@v5\n        with:\n          commit_message: \"doc: Generated help files\"\n          branch: ${{ github.head_ref }}\n```\n\nThis basically runs `git checkout`, `pandoc mREADME.md README.md -t markdoc.lua -o doc/markdoc.txt`, `git add .` and `git commit -m \"doc: Generated help files\"`.\n\n### 📌 Configuring workflow\n\nThe workflow comes with a single option, `config`. It's a JSON string that actually looks like this,\n\n```json\n{\n  \"doc/markdoc.txt\": [ \"mREADME.md\", \"README.md\" ]\n}\n```\n\nThis generates `markdoc.txt` from `mREADME.md`(this file is used for metadata) and `README.md`.\n\nYou can add more keys to create more files. For example,\n\n```json\n{\n  \"doc/markdoc.txt\": [ \"mREADME.md\", \"README.md\" ],\n  \"doc/markdoc-arch.txt\": [ \"ARCHITECTURE.md\" ]\n}\n```\n\nThis will generate another help file named `markdoc-arch` from the `ARCHITECTURE.md` file.\n\n---\n\nAs of `v3` there is also a `help_dirs` option. This is a JSON list of directories where `helptags` will be run.\n\n```json\n[ \"doc\" ]\n```\n\nBy default it only runs on the `doc/` directory.\n\n## 🪨 Limitations\n\n\u003e[!IMPORTANT]\n\u003e `markdoc` is best-effort only. It's not perfect but for most use cases it should be good enough.\n\n- Whitespace loss, due to the nature of syntax trees the whitespace in the document may not be preserved.\n- Issues with complex characters, some UTF-8 characters don't get properly wrapped(either due to multi-byte width or limitation of Lua).\n- Issues with complex document structures, though `markdoc` should support complex documents it is still preferable to keep them simple.\n\n  You may encounter text wrapping issues if the document gets too deeply nested(due to lack of space).\n\n## 🔩 Configuration\n\n\u003cp align=\"center\"\u003e\"One function to rule them all,\u003c/p\u003e\n\u003cp align=\"center\"\u003eOne function to find them,\u003c/p\u003e\n\u003cp align=\"center\"\u003eOne function to bring them all,\u003c/p\u003e\n\u003cp align=\"center\"\u003eAnd in the darkness bind them.\"\u003c/p\u003e\n\nYou can configure `markdoc` for a file by adding a YAML metadata section to the start of the file.\n\nIt should look something like this,\n\n```text\n---\nmarkdoc:\n  textwidth: 78\n  title: \"Markdown 🤝 Vimdoc\"\n  title_tag: \"markdoc\"\n\n  tags:\n    Features$: [ \"markdoc-features\", \"markdoc-feat\" ]\n  Usage$: [ \"markdoc-usage\" ]\n---\nSome text.\n```\n\n\u003e[!NOTE]\n\u003e All configuration options should be inside `markdoc`.\n\nThe configuration options are given below,\n\n### block_quotes\n\nChanges block quote configuration.\n\n#### Example\n\n```yaml\n  block_quotes:\n    default:\n      border: \"║\"\n\n    # Name SHOULD be in lowercase.\n    # This will match any variation of,\n    # [!CUSTOM]\n    custom:\n      border: \"┊\" # Block quote border\n      callout: \"🎵 Custom\" # Text to show at the top\n      icon: \"🎵\" # Icon before title(if there is any).\n```\n\n### fold_refs\n\nWhen `true`, link \u0026 image references are folded.\n\n#### Example\n\n```yaml\n  fold_refs: true\n```\n\n### foldmarkers\n\nMarkers used for folding.\n\n#### Example\n\n```yaml\n  # This is the same as `:set foldmarker`\n  foldmarkers: \"{{{,}}}\"\n```\n\n### tags\n\nTag configuration for different headings.\n\n#### Example\n\n```yaml\n    tags:\n      # The key is a Lua patter.\n      Features$: [ \"markdoc-features\", \"markdoc-feat\" ] # Adds 2 tags to headings ending with Feature.\n      Usage$: [ \"markdoc-usage\" ]\n```\n\n### table\n\nTable configuration.\n\n#### Example\n\n```yaml\n    table:\n      col_minwidth: 10 # Minimum width for columns.\n\n      top: [ \"╭\", \"─\", \"╮\", \"┬\" ]\n      header: [ \"│\", \"│\", \"│\" ]\n\n      separator: [ \"├\", \"─\", \"┤\", \"┼\" ]\n      header_separator: [ \"├\", \"─\", \"┤\", \"┼\" ]\n      row_separator: [ \"├\", \"─\", \"┤\", \"┼\" ]\n\n      row: [ \"│\", \"│\", \"│\" ]\n      bottom: [ \"╰\", \"─\", \"╯\", \"┴\" ]\n```\n\n### textwidth\n\nWidth of the document.\n\n#### Example\n\n```yaml\n  # Same as `:set textwidth`\n  textwidth: 78\n```\n\n### title\n\nTitle of the document.\n\n#### Example\n\n```yaml\n  title: \"Markdown 🤝 Vimdoc\"\n```\n\n### title_tag\n\nTag for the document title.\n\n#### Example\n\n```yaml\n  title_tag: \"markdoc\"\n```\n\n### toc_title\n\nTitle for the generated table of contents section.\nDefaults to `Table of contents:` when unset.\n\n#### Example\n\n```yaml\n  toc_title: \"Markdoc: TOC\"\n```\n\n### toc\n\nEntries for the table of contents.\n\n\u003e[!TIP]\n\u003e You can add `\u003cMKDocTOC/\u003e` to anywhere in your document and the table of contents will be placed there!\n\u003e However, It will also only replace the 1st one.\n\n#### Example\n\n```yaml\n  toc:\n    \"Features\": \"markdoc-features\"\n```\n\n------\n\nVimdoc version, see `doc/markdoc.txt`.\nMarkdown version, see `README.md`(metadata is at `mREADME.md`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxy2dev%2Fmarkdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxy2dev%2Fmarkdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxy2dev%2Fmarkdoc/lists"}