{"id":19356318,"url":"https://github.com/andrewpillar/mdsrv","last_synced_at":"2026-04-13T06:11:16.166Z","repository":{"id":64302404,"uuid":"282060137","full_name":"andrewpillar/mdsrv","owner":"andrewpillar","description":"Simple Markdown document server","archived":false,"fork":false,"pushed_at":"2021-01-10T18:25:14.000Z","size":25,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-06T17:48:05.682Z","etag":null,"topics":["documentation","documentation-tool","go","markdown"],"latest_commit_sha":null,"homepage":"","language":"Go","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/andrewpillar.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-07-23T21:35:42.000Z","updated_at":"2023-08-18T15:42:55.000Z","dependencies_parsed_at":"2023-01-15T09:45:27.018Z","dependency_job_id":null,"html_url":"https://github.com/andrewpillar/mdsrv","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewpillar%2Fmdsrv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewpillar%2Fmdsrv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewpillar%2Fmdsrv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewpillar%2Fmdsrv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewpillar","download_url":"https://codeload.github.com/andrewpillar/mdsrv/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240468843,"owners_count":19806265,"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","documentation-tool","go","markdown"],"created_at":"2024-11-10T07:03:58.387Z","updated_at":"2025-11-17T06:04:00.157Z","avatar_url":"https://github.com/andrewpillar.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mdsrv\n\nmdsrv is a utility for serving Markdown files over HTTP. You point it at a\ndirectory, and the server will map the request path to a Markdown file on the\nfilesystem.\n\n* [Quickstart](#quickstart)\n* [Serving Markdown](#serving-markdown)\n* [Template File](#template-file)\n* [Markdown Variables](#markdown-variables)\n* [Enabling TLS](#enabling-tls)\n\n## Quickstart\n\nIf you have Go installed then you can simply clone this repository, and build\nit from source via `go build`.\n\n    $ git clone https://github.com/andrewpillar/mdsrv\n    $ cd mdsrv\n    $ ./make.sh\n\nOnce built you can use it to start serving files,\n\n    $ ./mdsrv.out\n    2006/01/02 15:04:05 INFO   serving markdown documents in . on :8080\n\nby default it will bind to `:8080`, and serve files from the current directory.\nIf no template file is specified, then the plain text of the Markdown files will\nbe served, instead of being parsed.\n\n## Serving Markdown\n\nmdsrv allows for serving Markdown either as their plain text files, or as\nrendered HTML. By default, if no template file is given, then all of the\nMarkdown files will be served as plain text.\n\nBy default mdsrv will treat all `readme.md` files as the index for a directory\nthat is being served. So if the URI points to a directory, or is `/`, then\nmdsrv will look for a `readme.md` to try and serve. Each URI is mapped directly\nto a corresponding Markdown file with the appended `.md` suffix. For example,\nif the URI `/docs/user` is requested, then mdrsrv will look for a file at the\nlocation of `/docs/user.md`.\n\nThe plain text of a Markdown file can be viewed by setting the `Accept` header\nin the HTTP request to `text/plain`.\n\n## Template File\n\nThe template file is used for structuring how each Markdown document will be\nrendered when served as HTML. This is specified via the `-tmpl` flag given to\n`mdsrv`,\n\n    $ mdsrv -tmpl document.tmpl\n\nthe template file will have access to two variables, `Title`, and `Document`.\nThe `Title` variable will be the title of the document that is derived from the\nname of the Markdown file itself. The `Document ` variable will be the rendered\nHTML of the Markdown document. You can then use these values to create a\ntemplate page for each Markdown file to be rendered into,\n\n    \u003c!DOCTYPE HTML\u003e\n    \u003chtml lang=\"en\"\u003e\n        \u003chead\u003e\n            \u003cmeta charset=\"utf-8\"\u003e\n            \u003ctitle\u003e{{ .Title }}\u003c/title\u003e\n        \u003c/head\u003e\n        \u003cbody\u003e{{ .Document }}\u003c/body\u003e\n    \u003c/html\u003e\n\n## Markdown Variables\n\nVariables can be passed through to the server Markdown documents via the `-var`\nflag. For example,\n\n    $ mdsrv -var host=https://example.com\n\nthis variable can then be accessed from within a Markdown document like so,\n\n    Host is {{index .Vars \"host\"}}\n\n## Enabling TLS\n\nTLS can be enabled via the `-cert` and `-key` flags. This take paths to the TLS\ncertificate and key to use respectively.\n\n    $ mdsrv -cert /var/lib/ssl/server.crt -key /var/lib/ssl/server.key\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewpillar%2Fmdsrv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewpillar%2Fmdsrv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewpillar%2Fmdsrv/lists"}