{"id":13816625,"url":"https://github.com/pysan3/minorg","last_synced_at":"2025-08-19T05:10:30.223Z","repository":{"id":204350775,"uuid":"711630531","full_name":"pysan3/minorg","owner":"pysan3","description":"pandoc -\u003e norg converter written in the Nim language.","archived":false,"fork":false,"pushed_at":"2024-02-24T12:49:53.000Z","size":770,"stargazers_count":36,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-13T02:41:54.362Z","etag":null,"topics":["nim","nimble","norg","pandoc"],"latest_commit_sha":null,"homepage":"https://pysan3.github.io/minorg","language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pysan3.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}},"created_at":"2023-10-29T20:54:28.000Z","updated_at":"2025-05-15T21:22:21.000Z","dependencies_parsed_at":"2023-10-31T05:26:32.507Z","dependency_job_id":"1c0aa968-f180-4a6f-846f-12ee70d4cc64","html_url":"https://github.com/pysan3/minorg","commit_stats":null,"previous_names":["pysan3/nim_norg","pysan3/minorg"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/pysan3/minorg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pysan3%2Fminorg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pysan3%2Fminorg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pysan3%2Fminorg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pysan3%2Fminorg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pysan3","download_url":"https://codeload.github.com/pysan3/minorg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pysan3%2Fminorg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271103202,"owners_count":24699646,"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","status":"online","status_checked_at":"2025-08-19T02:00:09.176Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["nim","nimble","norg","pandoc"],"created_at":"2024-08-04T05:00:48.023Z","updated_at":"2025-08-19T05:10:30.189Z","avatar_url":"https://github.com/pysan3.png","language":"Nim","funding_links":[],"categories":["Parsers","Nim"],"sub_categories":[],"readme":"# minorg\n\n![Minimum supported Nim version](https://img.shields.io/badge/nim-2.0.0%2B-informational?style=flat\u0026logo=nim) [![License](https://img.shields.io/github/license/pysan3/minorg?style=flat)](LICENSE)\n\n\u003e MyNorg: Convert all *my* notes into [`norg`](https://github.com/nvim-neorg/neorg/) format.\n\n`Pandoc json` -\\\u003e `norg` converter written in [Nim](https://nim-lang.org/) language.\n\n\\*This README is generated from [./README.norg](./README.norg).\n\n## Table of Contents\n\n- [Get Started](#get-started)\n- [Usage](#usage)\n  - [Command](#command)\n  - [Example](#example)\n- [Known Issues](#known-issues)\n  - [Obsidian](#obsidian)\n- [Compile From Source](#compile-from-source)\n- [Contribution](#contribution)\n- [License](#license)\n\n## Get Started\n\n- Download: \u003chttps://github.com/pysan3/minorg/releases\u003e\n- API documentation: \u003chttps://pysan3.github.io/minorg/\u003e\n\n## Usage\n\n### Command\n\n- `minorg help`\n\n``` txt\nThis is a multiple-dispatch command.  -h/--help/--help-syntax is available\nfor top-level/all subcommands.  Usage is like:\n    minorg {SUBCMD} [subcommand-opts \u0026 args]\nwhere subcommand syntaxes are as follows:\n\n  generate [optional-params]\n  Options:\n      --version            bool    false  print version\n      -i=, --input=        string  \"\"     Input file. Leave it blank to use stdin.\n      -o=, --output=       string  \"\"     Output file. Leave it blank to use stdout.\n      -v, --verbose        bool    false  Outputs debug info to stderr.\n      -f, --force          bool    false  Overwrite files and create parent folders if needed.\n      --isObsidian         bool    false  set isObsidian\n      -w=, --workRootDir=  string  \"\"     set workRootDir\n```\n\n### Example\n\n#### Pandoc and Usage\n\n[Pandoc](https://pandoc.org/) is able to convert files from one markup format into another. We use this tool to parse arbitrary markup format into its AST represented in `json` format as defined in [Pandoc Type Definition](https://hackage.haskell.org/package/pandoc-types-1.23/docs/Text-Pandoc-Definition.html).\n\nPandoc accepts two arguments `-f` (from) and `-t` (to) to specify the format of the file. As noted above, we want the `json` representation so the output must be `-t json`.\n\n``` bash\n$ pandoc -f '\u003cfile-format\u003e' -t json '\u003cinput-file-name\u003e' | minorg generate -o '\u003coutput-file-name\u003e.norg'\n```\n\nThe input file format depends on the file you want to convert from. Here is a list of some common files.\n\n- `markdown`: markdown format (`.md`), Obsidian file\n- `gfm`: GitHub-flavored Markdown\n- `html`: HTML4 / HTML5\n- `latex`: LaTeX document\n\nRead [this page](https://pandoc.org/index.html) for information on more file formats.\n\n#### Basic Usage\n\n- Use `-i`, `-o` flags (`--input`, `--output`)\n\n``` bash\n$ pandoc -f markdown -t json -o parsed.json ./your/markdown/file.md\n$ minorg generate -i parsed.json -o output.norg\n```\n\n- Use `stdin`, `stdout`\n\n``` bash\n$ pandoc -f markdown -t json ./your/markdown/file.md | minorg generate \u003e output.norg\n```\n\n#### Other Useful Flags\n\n- `-v`, `--verbose`\n  - Please use this flag to report issues.\n- `-f`, `--force`\n  - Force overwrite output file if exists.\n  - Also automatically creates parent directories if not exists.\n\n#### **Obsidian** Notes\n\nThis parser also takes some amount of care of obsidian specific format. Please use the `--isObsidian` flag and read [Obsidian](#obsidian) section for more information.\n\n#### Recursive Directory of Markdown\n\nThis is a shell script which scans the folder recursively for files with `\"*.md\"` extension and applies `pandoc -\u003e minorg` compo to those files. This converts `foo/bar.md` into `foo/bar.md.norg`. However I will suggest first trying out few files manually to check if this converter generates the desired output for you. If you are satisfied, go for all, if you are not, feel free to [submit a support request](https://github.com/pysan3/minorg/issues/new?assignees=\u0026labels=generate\u0026projects=\u0026template=converter_issues.yml\u0026title=FEATURE%3A+or+BUG%3A+).\n\n``` bash\ncommand find . -type f -name '*.md' | while read f; do\n  pandoc -f markdown -t json \"$f\" | minorg generate -o \"${f}.norg\"\ndone\n```\n\n## Known Issues\n\n### File Linking\n\nIt is very hard to distinguish what link pattern should be used.\n\n- [x] URL: `{https://xxx.example.com}`\n  - [x] URL with name: [Neorg GitHub](https://github.com/nvim-neorg/neorg/)\n- [ ] Norg files\n  - [ ] Relative to current file: `{:foo/bar:}` -\\\u003e `foo/bar.norg`\n  - [ ] Absolute path: `{:/tmp/foo/bar:}` -\\\u003e `/tmp/foo/bar.norg`. (Also works with `~/` = `$HOME/`)\n  - [ ] Relative to current workspace: `{:$/foo/bar:}` -\\\u003e `~/Norg/Notes/foo/bar.norg`\n  - [ ] Relative to different workspace: `{:$work/foo/bar:}` -\\\u003e `~/Norg/work/foo/bar.norg`\n- [ ] Usual files: `{/ /path/to/file}`\n- [x] Headings: [Heading 1](#heading-1)\n  - [x] Any level heading: [Heading 2](#heading-2)\n\n**AND YOU CAN COMBINE THEM**\n\n- [ ] `Heading 1` of `foo/bar.norg`: [Heading 1](foo/bar.norg#heading-1)\n- [ ] Line numbers: [foo/bar](foo/bar.norg)\n\n### `|example` Is Not Restored Correctly\n\nThis is a problem in `norganic` / `Norg.jl`.\n\n- [x] I will make a PR later.\n  - \u003chttps://github.com/Klafyvel/Norg.jl/issues/41\u003e\n- [ ] He says he needs some help [here](https://github.com/Klafyvel/Norg.jl/issues/41#issuecomment-1784814268).\n- [x] Auto convert `@code norg` -\\\u003e `|example`\n\n### Softbreak Not Preserved\n\nWhen the original note (especially markdown) had softbreaks (single new line to format the document but does not mean a new paragraph), that new line does not get transferred to the generated file.\n\n- [x] fix softbreak\n- [x] Modifier chars (i.e. **bold**, *italic*, ...) cannot be escaped when they are used as a real symbol.\n\n### Markdown TODO Not Working\n\nAccording to `pandoc -f markdown -t json`, bullet list with todo (`- [ ]`) is treated as a simple `[\"-\", \" \", \"[\", \" \", \"]\"]` which cannot be converted to norg style (`- ( )`).\n\n- [x] Fix markdown style todo items\n\n### Obsidian\n\n#### Obsidian Style Tags Are Not Working\n\nIt seems that when the line above a header is not empty, pandoc does not recognize it as a header but rather a paragraph.\n\n``` markdown\n#obsidiantag1 #obsidiantag2\n# A Header\n```\n\n- [x] Convert them to tags in `norg` format\n  - ❗ Use the `--isObsidian` flag to enable this parse mode.\n  - Also pass `--workRootDir=/path/to/workspace` to link with other files (Required).\n\n#### Wikilinks Are Not Working\n\nObsidian uses its own format to link to other files in the directory. Obviously this is not an official markdown syntax, and pandoc cannot parse it.\n\n``` markdown\n[[file name]] -\u003e `./somewhere/in/the/directory/file\\ name.md`\n![[file name]] -\u003e `./somewhere/in/the/directory/file\\ name.png` # Image support\n```\n\n- [x] Implement a workaround\n  - See [Obsidian Style Tags Are Not Working](#obsidian-style-tags-are-not-working) for the fix.\n    - `--isObsidian` and `--workRootDir` required.\n  - TODOs\n    - [x] `[[file name]]` -\\\u003e `{:$/somewhere/in/workspace/file name:}` (norg file)\n    - [x] `[[file name.txt]]` -\\\u003e `{/ $/somewhere/in/workspace/file name.txt}` (normal file)\n    - [x] `![[file name.png]]` -\\\u003e `.image $/somewhere/in/workspace/file\\ name.png` (image file)\n    - [x] `[[file name#header]]` -\\\u003e `{:$/somewhere/in/workspace/file name:# head1}` (norg file with any level heading)\n    - [x] `[[file name#head1#head2]]` -\\\u003e `{:$/somewhere/in/workspace/file name:* head1 : ** head2}` (norg file with chained headings)\n    - [x] `[[file name|display name]]` -\\\u003e `{:$/somewhere/in/workspace/file name:}[display name]` (norg file with display name)\n    - [x] `[[file name.txt|display name]]` -\\\u003e `{/ $/somewhere/in/workspace/file name.txt}[display name]` (normal file with display name)\n    - [x] `![[file name.png|display name]]` -\\\u003e `.alt display\\ name\\\\n.image $/somewhere/in/workspace/file\\ name.png` (image file with alt text)\n    - [x] `[[unknown]]` -\\\u003e `[[unknown]]` (file not found: do nothing)\n\n## Compile From Source\n\nThis project is written in [nim](https://nim-lang.org/) language. You will need the nim compiler and the package manager `nimble`.\n\n#### Install `choosenim` and `nim` Compiler\n\nIf you don't have nim installed yet, I strongly suggest using [choosenim](https://github.com/dom96/choosenim) to install the required toolkit. Please read the [Choosenim Installation](https://github.com/dom96/choosenim#installation). Below is the instruction for unix systems.\n\n``` bash\n$ curl https://nim-lang.org/choosenim/init.sh -sSf | sh\n$ export PATH=\"$HOME/.nimble/bin:$PATH\"\n$ choosenim stable\n# install stable version of nim and nimble\n# ... this may take a while\n$ nim -v\n# ! check nim version \u003e= 2.0.0\n```\n\n#### Setup `nimble` and Compile\n\n`nimble` is the package manager for nim (should be installed into `$HOME/.nimble/bin` by choosenim). Setup for this repo is very easy.\n\n``` bash\n$ git clone https://github.com/pysan3/minorg.git\n$ cd minorg/\n$ nimble setup\n# ... Download dependencies and setup the environment.\n$ nimble build -d:release\n# Compile ./minorg.nim (you may omit -d:release)\n$ ./minorg help\n# Run compiled binary. Pass `help` as an argument to get started.\n```\n\n## Contribution\n\nAny contribution is welcome! And don't hesitate to [send me an issue](https://github.com/pysan3/minorg/issues/new/choose).\n\n#### Fix Code and Recompile\n\n``` bash\n$ pandoc -f markdown -t json -o parsed.json your-test-markdown-file.md\n$ nim r ./minorg.nim generate -i parsed.json -v\n```\n\nRun `nim r ./minorg.nim help` for more options.\n\n## License\n\nAll files in this repository without annotation are licensed under the **GPL-3.0 license** as detailed in [LICENSE](LICENSE).\n\n## Other Projects\n\n- [`norg-pandoc`](https://github.com/boltlessengineer/norg-pandoc)\n  - `norg` -\\\u003e `pandoc` exporter written in lua.\n- [`norganic`](https://github.com/klafyvel/norganic) + [`Norg.jl`](https://github.com/Klafyvel/Norg.jl/)\n  - Another `norg` -\\\u003e `pandoc` exporter written in julia.\n  - Parser is written in `Norg.jl` and `norganic` is its frontend to be used from the command line.\n- [`tree-sitter-norg3`](https://github.com/nvim-neorg/tree-sitter-norg3)\n  - Parser of the norg format written for tree-sitter.\n  - Once this is mature, we should not require `minorg` anymore as this parser should handle the work better.\n- [`Norg-Tutorial`](https://github.com/pysan3/Norg-Tutorial)\n  - Tutorial for the norg file format and neorg plugin.\n  - Read the [Export / Import](https://github.com/pysan3/Norg-Tutorial/blob/main/norg_tutorial.md#export--import) section for more explanation to export / import your notes to and from norg files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpysan3%2Fminorg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpysan3%2Fminorg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpysan3%2Fminorg/lists"}