{"id":30269061,"url":"https://github.com/jraygauthier/pandoc-md-wiki","last_synced_at":"2025-08-16T01:39:15.191Z","repository":{"id":77054449,"uuid":"226209405","full_name":"jraygauthier/pandoc-md-wiki","owner":"jraygauthier","description":"A simple markdown wiki build tool based on pandoc and tailored to needs of development teams.","archived":false,"fork":false,"pushed_at":"2024-11-27T20:51:14.000Z","size":93,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-16T01:32:06.979Z","etag":null,"topics":["developer-tools","development-tools","diagrams","doc","documentation","documentation-tool","graphviz","haskell-diagrams","markdown","pandoc","pandoc-filter","pandoc-markdown","plantuml","static-site","static-site-generator","static-website","vscode","vscode-extension","vscode-settings","wiki"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/jraygauthier.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-05T23:50:09.000Z","updated_at":"2024-11-27T20:36:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"84e4a969-445a-4e05-9336-43a712cc487d","html_url":"https://github.com/jraygauthier/pandoc-md-wiki","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jraygauthier/pandoc-md-wiki","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jraygauthier%2Fpandoc-md-wiki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jraygauthier%2Fpandoc-md-wiki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jraygauthier%2Fpandoc-md-wiki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jraygauthier%2Fpandoc-md-wiki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jraygauthier","download_url":"https://codeload.github.com/jraygauthier/pandoc-md-wiki/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jraygauthier%2Fpandoc-md-wiki/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270657471,"owners_count":24623457,"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-15T02:00:12.559Z","response_time":110,"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":["developer-tools","development-tools","diagrams","doc","documentation","documentation-tool","graphviz","haskell-diagrams","markdown","pandoc","pandoc-filter","pandoc-markdown","plantuml","static-site","static-site-generator","static-website","vscode","vscode-extension","vscode-settings","wiki"],"created_at":"2025-08-16T01:39:13.729Z","updated_at":"2025-08-16T01:39:15.184Z","avatar_url":"https://github.com/jraygauthier.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"Readme\n======\n\n`pandoc-md-wiki`: a simple markdown wiki build tool based on [pandoc] tailored\nto the needs of development teams.\n\nThis tool is very simple and includes a pretty generic *makefile* which is meant\nto be included by a makefile at the root of the markdown wiki.\n\nThe main target builds a static html 5 web site to a companion directory\nalongside the markdown wiki. This directory by default has the same name as the\nmarkdown wiki with the target added as a suffix (in this case `-html`).\n\nThis tool includes the following [pandoc-filters]:\n\n -  `./.build-system/pandoc-filters/local-links-abs-to-rel.lua`\n\n    Changes local links absolute with regard to the site's root directory\n    to links relative to the current `.md` file.\n\n -  `./.build-system/pandoc-filters/local-links-to-target-ext.lua`\n\n    Changes local links targeting `.md` files so that once rendered to html these\n    links points to the `.html` version (or any other target format extension).\n\n -  `./.build-system/pandoc-filters/imports-to-link.lua`\n\n    Allow this tool to support `@import` statement like the one found\n    in [markdown-preview-enhanced].\n\n    Support it currently limited. See [TODO.md] for more details.\n\n -  `./.build-system/pandoc-filters/puml-cb-to-img.lua`\n\n    Allow this tool to convert code blocks marked as `puml` to be replaced by\n    the image resulting from running this code through [plantuml].\n\n -  More to come. See [TODO.md] for some ideas.\n\nFor the moment, we use only [pandoc-lua-filters] as these are supported natively\nand as such should incur less overhead then the haskell or python ones.\n\nAnother secondary goal of this tool is to be as compatible as possible with the\npandoc backed variant of the neat [markdown-preview-enhanced] tool which is\noffered as an extension to both the [vscode] and [atom] IDEs.\n\n\nRequirements\n------------\n\nYou should find a `shell.nix` at the root of this repository which should\nmake [nix] the only requirement to run this tool.\n\nYou might also want to install [direnv] tool which streamline / automate the\nloading of the nix environment as you enter the repository.\n\nSo, here's what you should install:\n\n -  [nix-install-instructions]\n -  [direnv-install-instructions]\n\n\nTesting the tool\n----------------\n\n```bash\n$ cd /path/to/pandoc-md-wiki\n# ..\n$ nix-shell\n# ..\n$ make html-and-preview\n```\n\nshould build a static html 5 web site from the embedded markdown file of this\nrepositories and open its index in your default browser.\n\nThese markdown files are meant to showcase the capabilities of this tool.\n\n\nBootstrapping your own pandoc markdown wiki\n-------------------------------------------\n\nHere's the simplest setup you need. At the root of your wiki repository (e.g.:\n`/path/to/my-wiki`) you should add the following files:\n\n`shell.nix`:\n\n```nix\n{}:\n\nlet\n  pandocMdWikiSrc = builtins.fetchTarball {\n    url = \"https://github.com/jraygauthier/pandoc-md-wiki/archive/0185bb3f0f42fe884a6f33baea07f05588a64813.tar.gz\";\n    # Get this info from the output of: `nix-prefetch-url --unpack $url` where `url` is the above.\n    sha256 = \"0n1srznampspcd5swpxifhis873iawvf51311pa7ycanif5fsry2\";\n  };\n\n  pandocMdWikiShell = import (pandocMdWikiSrc + \"/shell-external.nix\") {\n    # See \u003chttps://github.com/jraygauthier/pandoc-md-wiki/blob/master/.build-system/vscode/README.md\u003e\n    # for more info about this option.\n    # withVscodeSupport = true;\n  };\nin\n\npandocMdWikiShell\n```\n\nHere, `0185bb3f0f42fe884a6f33baea07f05588a64813` right of `url` should be\nreplaced by the latest *git revision* of this repository.\n\nHere, the `0n1srznampspcd5swpxifhis873iawvf51311pa7ycanif5fsry2` value right of\n`sha256` should be replaced by the output of `nix-prefetch-url --unpack $url`.\nAlternatively, you can change a single of its digit and attempt entering the\nnix shell environment where your will be offered with the proper value for\nthis field.\n\n\n`Makefile`:\n\n```Makefile\nMKF_DIR := $(abspath $(dir $(abspath $(lastword $(MAKEFILE_LIST)))))\n\n# Inputs for the included makefile.\nPANDOC_MD_WIKI_ROOT_DIR := $(MKF_DIR)\n\n# Exported via 'pandoc-md-wiki/shell.nix' 'shellHook'.\nifndef PANDOC_MD_WIKI_RELEASE_MAKEFILE\n  $(error Missing 'PANDOC_MD_WIKI_RELEASE_MAKEFILE' env variable.)\nendif\ninclude $(PANDOC_MD_WIKI_RELEASE_MAKEFILE)\n```\n\n`Home.md`:\n\n```md\nMy home page title\n==================\n\nHere is my home page content.\n```\n\nand optionally if you mean to use *direnv*:\n\n`envrc`:\n\n```bash\nuse nix\n```\n\nYou should then be able to enter the nix environment:\n\n```bash\n$ cd /path/to/my-wiki\n# If you are using direnv, you should instead call\n# 'direnv allow' instead of `nix-shell`.\n$ nix-shell\n# ..\n$ make html-and-preview\nxdg-open \"../my-wiki-html/Home.html\"\n```\n\nThis should open the rendered version of your *home page* in your default browser.\n\n\nUsing the gnumake build system (aka Makefile)\n---------------------------------------------\n\n**TIP**: The provided make file supports tab completion (\n`make [Hit tab key here to get the list of top level tagets]`) and provides\nmultiple top level targets, namely:\n\n -  `html`: build the wiki to html without preview.\n -  `clean-html`: clean the html output leaving any dot directories at the root\n    of the output (including `.git`) but also any regular files which are not a\n    target of the makefile (e.g.: `README.md`, `LICENSE`, `.gitignore`, etc).\n -  `ls-html`: list the files in the html output.\n -  `rls-html`: list recursively the files in the html output.\n -  `preview-html`: preview currently built html home page if any.\n -  `clean-html-only `: clean only the html files from the html output (i.e: not\n    the diagrams).\n -  `clean-html-img`: clean only the html image files from the html output\n    (including the generated ones).\n -  `clean-html-svg-from-puml-only`: clean only the svg generated from the puml\n    diagrams.\n -  `clean`: clean all outputs.\n -  `all`: build all outputs.\n -  `force-clean-html-whole-dir`: clean the html output directory recursively.\n -  `debug-vars`: debug the build system's internal variables.\n -  etc.\n\n\nVscode support\n--------------\n\nSee [pandoc-md-wiki - vscode support].\n\n\nLimitations\n-----------\n\n -  As we're using gnumake to build the wiki and that this tool notoriously does not support\n    spaces in file correctly, **do not use spaces in you filenames**.\n\n    If your really do want to support this, you might instead use a more\n    advanced build system such as [shake] or [scons].\n\n    You might even go the full fledged static site generator way with the such\n    as [hakyll], [jekyll] or [hugo].\n\n    See [TODO.md] for potential improvements aimed at fixing this.\n\n\nRelated tools / systems\n-----------------------\n\n -  [pandoc-scholar]\n\n     -  [Formatting Open Science: agilely creating multiple document formats for\n        academic manuscripts with Pandoc Scholar](\n        https://pandoc-scholar.github.io/)\n\n -  [pandocomatic]\n\n     -  [Chapter 6. Converting a directory tree of\n        documents](https://heerdebeer.org/Software/markdown/pandocomatic/#converting-a-directory-tree-of-documents)\n\n -  [simple-template/pandoc]\n\n     -  [Wiki](https://github.com/simple-template/pandoc/wiki)\n\n -  [hakyll]\n\n -  [jekyll]\n\n -  [hugo]\n\n -  [pdsite]\n\n -  [bookdown]\n\n -  [pp]\n\n    A alternative approach by implementing a very powerful preprocessor.\n\n -  [Pandoc Extras]\n\n     -  [Tools for Websites](https://github.com/jgm/pandoc/wiki/Pandoc-Extras#tools-for-websites)\n     -  [Workflow](https://github.com/jgm/pandoc/wiki/Pandoc-Extras#workflow)\n\n\nLicense\n-------\n\n`pandoc-md-wiki` is licensed under the [Apache License].\n\nThis license is very permissive, so feel free to fork this repository publicly\n(or even privately if absolutely required) to make it more suitable to your own\nuse case.\n\nThis work is an improvement of the ideas from the following tools which I,\n[Raymond Gauthier], developed on my spare time years again (as far back as 2015)\nto support my own personal private wiki and made public at the following\nlocations:\n\n -  [jrg_wiki_pandoc_converter]\n -  [jrg-gitit-plugins]\n\nAs the sole author (well almost, see exeption below) of these tools, I hereby\ngrant the permission to use those ideas (derived from the work not in the list\nbelow) in their *current* (i.e: `pandoc-md-wiki`) form (lua filters instead of\nhaskell ones, makefile instead of bash script, etc) under the more permissive\n[Apache License] hopefully for the benefit of all.\n\n -  [jgm/gitit/plugins]\n\n    Were taken from the above example plugin list:\n\n     -  [jrg-gitit-plugins/src/Network/Gitit/Plugins/ImgTex.hs]\n     -  [jrg-gitit-plugins/src/Network/Gitit/Plugins/Dot.hs]\n     -  [jrg-gitit-plugins/src/Network/Gitit/Plugins/ShowUser.hs]\n\nThanks to [John MacFarlane] the author of [pandoc], its maintainers and\ncontributors which now allows us to make such incredible documentation\nautomation tools.\n\n\n[John MacFarlane]: https://johnmacfarlane.net/\n[jgm/gitit/plugins]: https://github.com/jgm/gitit/tree/master/plugins\n[jrg-gitit-plugins/src/Network/Gitit/Plugins/ImgTex.hs]: https://github.com/jraygauthier/jrg-gitit-plugins/blob/master/src/Network/Gitit/Plugins/ImgTex.hs\n[jrg-gitit-plugins/src/Network/Gitit/Plugins/Dot.hs]: https://github.com/jraygauthier/jrg-gitit-plugins/blob/master/src/Network/Gitit/Plugins/Dot.hs\n[jrg-gitit-plugins/src/Network/Gitit/Plugins/ShowUser.hs]: https://github.com/jraygauthier/jrg-gitit-plugins/blob/master/src/Network/Gitit/Plugins/ShowUser.hs\n\n\nContributing\n------------\n\nIf you have nice changes that would improve this tool, we accept pull requests.\n\nTake not however that the tool is meant as a *generic* wiki build system, so your\nchanges should meet this design criteria to be accepted (i.e: changes which are\ntoo specific to a particular use case won't be accepted).\n\n\n[TODO.md]: ./TODO.md\n\n[Apache License]: ./LICENSE\n[LICENSE]: ./LICENSE\n\n[pandoc]: https://pandoc.org/\n[pandoc-filters]: https://pandoc.org/filters.html\n[pandoc-lua-filters]: https://pandoc.org/lua-filters.html\n[markdown-preview-enhanced]: https://shd101wyy.github.io/markdown-preview-enhanced\n[vscode]: https://code.visualstudio.com/\n[atom]: https://atom.io/\n[nix]: https://nixos.org/nix/\n[direnv]: https://direnv.net/\n[nix-install-instructions]: https://nixos.org/nix/download.html\n[direnv-install-instructions]: https://direnv.net/docs/installation.html\n\n[plantuml]: https://plantuml.com/\n\n[shake]: http://hackage.haskell.org/package/shake\n[scons]: https://www.scons.org/\n\n[pandoc-scholar]: https://github.com/pandoc-scholar/pandoc-scholar\n[pandocomatic]: https://heerdebeer.org/Software/markdown/pandocomatic/\n[simple-template/pandoc]: https://github.com/simple-template/pandoc\n[hakyll]: https://jaspervdj.be/hakyll/\n[jekyll]: https://jekyllrb.com/\n[hugo]: https://gohugo.io/\n[pdsite]: http://pdsite.org/\n[bookdown]: https://bookdown.org/yihui/bookdown/\n[pp]: https://github.com/CDSoft/pp\n[Pandoc Extras]: https://github.com/jgm/pandoc/wiki/Pandoc-Extras\n\n[pandoc-md-wiki - vscode support]: ./.build-system/vscode/README.md\n\n[Raymond Gauthier]: https://github.com/jraygauthier/\n[jrg_wiki_pandoc_converter]: https://github.com/jraygauthier/jrg_wiki_pandoc_converter\n[jrg-gitit-plugins]: https://github.com/jraygauthier/jrg-gitit-plugins\n[jrg-gitit]: https://github.com/jraygauthier/jrg-gitit\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjraygauthier%2Fpandoc-md-wiki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjraygauthier%2Fpandoc-md-wiki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjraygauthier%2Fpandoc-md-wiki/lists"}