{"id":21680823,"url":"https://github.com/brunobord/static-markdown","last_synced_at":"2025-04-12T06:25:24.205Z","repository":{"id":51725730,"uuid":"191825473","full_name":"brunobord/static-markdown","owner":"brunobord","description":"A static HTTP server, with markdown rendering mechanism","archived":false,"fork":false,"pushed_at":"2021-05-10T13:28:55.000Z","size":999,"stargazers_count":4,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T01:51:08.322Z","etag":null,"topics":["gfm","http","markdown","python","python3","server","static-server"],"latest_commit_sha":null,"homepage":"","language":"Python","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/brunobord.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-13T20:00:58.000Z","updated_at":"2022-01-09T14:34:35.000Z","dependencies_parsed_at":"2022-08-23T04:01:09.008Z","dependency_job_id":null,"html_url":"https://github.com/brunobord/static-markdown","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunobord%2Fstatic-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunobord%2Fstatic-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunobord%2Fstatic-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunobord%2Fstatic-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brunobord","download_url":"https://codeload.github.com/brunobord/static-markdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248027382,"owners_count":21035594,"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":["gfm","http","markdown","python","python3","server","static-server"],"created_at":"2024-11-25T15:21:23.866Z","updated_at":"2025-04-12T06:25:24.158Z","avatar_url":"https://github.com/brunobord.png","language":"Python","readme":"# Static Markdown\n\nA static web server with markdown rendering feature.\n\nIt serves regular HTTP content (HTML, JS, CSS, images, etc), but when you're browsing a ``.md``, ``.mdown`` or ``.markdown`` file, it's converted into HTML and rendered as a (hopefully) readable page.\n\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/static-markdown)\n![Travis CI status](https://img.shields.io/travis/com/brunobord/static-markdown)\n\n## IMPORTANT WARNING\n\n**This server is not recommended for production. It's a toy to serve static files and Markdown content, but there's no guarantee about security, performance, availability, etc.**\n\n## Installation\n\n### via PyPI\n\nInstall this tool using pip to download it [from PyPI](https://pypi.org/project/static-markdown/). You may prefer to use a virtualenv, but you may also want to install \"user-wide\".\n\n```shell\npip install static-markdown\npip install --user static-markdown\n```\n\n### Using the source\n\nWe're advising you to use ``virtualenv`` to install this package. Clone this repository, and, inside your *virtualenv*, run the following:\n\n```shell\npip install -e ./\n```\n\n## Usage\n\nOnce it's installed, you can just change your current shell session to the designated directory and run the following:\n\n```shell\ncd /path/to/directory\nserve-md\n```\n\nAlternatively, you can also run this command line from anywhere, but set the target path as a command argument:\n\n```shell\nserve-md /path/to/directory\n```\n\nUsing these default option, you can now browse your \"static website\" by pointing your browser to: \u003chttp://127.0.0.1:8080/\u003e.\n\nStop the server with Ctrl-C.\n\n### Options\n\n```\nusage: serve-md [-h] [-p PORT] [--markdown-template MARKDOWN_TEMPLATE]\n                [--stylesheet STYLESHEET] [--version]\n                [root]\n\npositional arguments:\n  root                  Path to serve statically\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -p PORT, --port PORT  Port number (0-65535)\n  --markdown-template MARKDOWN_TEMPLATE\n                        Path to an alternate HTML template for Markdown files\n  --stylesheet STYLESHEET\n                        Path to a custom stylesheet\n  --version             Return version and exit\n```\n\n### Browsing\n\nLet's consider the following path tree:\n\n```\n.\n├── empty\n├── images\n│   └── knight.png\n├── index.html\n├── mdown\n│   └── index.md\n├── mdown-readme\n│   └── README.md\n└── subdir\n    └── index.html\n```\n\nHere is a table describing the different pages rendered with the given URL in your browser\n\n| URL                | Content                | Content type | Status Code           |\n|:-------------------|:-----------------------|:-------------|:----------------------|\n| /                  | index.html             | text/html    | 200 OK                |\n| /empty             | directory listing      | text/html    | 200 OK                |\n| /images/knight.png | knight.png (as binary) | image/png    | 200 OK                |\n| /mdown/            | index.md (as HTML)     | text/html    | 200 OK                |\n| /mdown/index.md    | index.md (as HTML)     | text/html    | 200 OK                |\n| /mdown-readme      | README.md (as HTML)    | text/html    | 200 OK                |\n| /subdir            | redirect to /subdir/   | -            | 301 MOVED PERMANENTLY |\n| /subdir/           | subdir/index.html      | text/html    | 200 OK                |\n\n### Indexes\n\nWhen browsing a directory, ``serve-md`` will look after the following files, in that specific order: \"index.html\", \"index.htm\", \"index.md\", \"README.md\", \"readme.md\". The first one of them to be found will be served as the index page of the directory.\n\nIf none of them is found, ``serve-md`` will return a directory listing. If you're using the \"Markdown template\" feature, it'll be used when rendering this page.\n\n### HTTP Verbs\n\nGET \u0026 HEAD verbs are implemented.\n\nPOST, PUT, DELETE will result into a 405 Method Not Allowed error.\n\n### Markdown templates\n\nBy default, Markdown files will be rendered as HTML using a minimal CSS. Using the ``--markdown-template`` option, you can use your own HTML template with a custom CSS to render generate the ``text/html``. You can find various examples in the ``example-options`` directory in the source repository.\n\nWe've used various minimalist CSS frameworks for rendering and layout:\n\n* [miligram](https://milligram.io/),\n* [mini css](https://minicss.org/),\n* [Github Markdown CSS](https://github.com/sindresorhus/github-markdown-css),\n\n### Custom styles\n\nIf the only thing you need is to customize styles, but not the structure of your HTML page, you can use the ``--stylesheet`` option to point at a CSS file.\n\nExample:\n\n```sh\nserve-md /path/to/directory --stylesheet ~/my-style.css\n```\n\n## Hack\n\n1. Clone this repository.\n2. Write tests.\n3. Implement stuff.\n4. Open a Pull Request.\n\n**Important:** Each time you're modifying any line of the server's code, if you want to test your patch **live**, you **HAVE** to stop and restart the application.\n\n### Run automated tests\n\nIn a shell session, run tests with:\n\n```shell\nmake test\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrunobord%2Fstatic-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrunobord%2Fstatic-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrunobord%2Fstatic-markdown/lists"}