Metadata-Version: 2.1
Name: static-markdown
Version: 0.4.0
Summary: A static web server with markdown rendering feature
Home-page: https://github.com/brunobord/static-markdown
Author: Bruno Bord
Author-email: bruno@jehaisleprintemps.net
License: MIT
Description: # Static Markdown
        
        A static web server with markdown rendering feature.
        
        It 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.
        
        ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/static-markdown)
        ![Travis CI status](https://img.shields.io/travis/com/brunobord/static-markdown)
        
        ## IMPORTANT WARNING
        
        **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.**
        
        ## Installation
        
        ### via PyPI
        
        Install 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".
        
        ```shell
        pip install static-markdown
        pip install --user static-markdown
        ```
        
        ### Using the source
        
        We're advising you to use ``virtualenv`` to install this package. Clone this repository, and, inside your *virtualenv*, run the following:
        
        ```shell
        pip install -e ./
        ```
        
        ## Usage
        
        Once it's installed, you can just change your current shell session to the designated directory and run the following:
        
        ```shell
        cd /path/to/directory
        serve-md
        ```
        
        Alternatively, you can also run this command line from anywhere, but set the target path as a command argument:
        
        ```shell
        serve-md /path/to/directory
        ```
        
        Using these default option, you can now browse your "static website" by pointing your browser to: <http://127.0.0.1:8080/>.
        
        Stop the server with Ctrl-C.
        
        ### Options
        
        ```
        usage: serve-md [-h] [-p PORT] [--markdown-template MARKDOWN_TEMPLATE]
                        [--stylesheet STYLESHEET] [--version]
                        [root]
        
        positional arguments:
          root                  Path to serve statically
        
        optional arguments:
          -h, --help            show this help message and exit
          -p PORT, --port PORT  Port number (0-65535)
          --markdown-template MARKDOWN_TEMPLATE
                                Path to an alternate HTML template for Markdown files
          --stylesheet STYLESHEET
                                Path to a custom stylesheet
          --version             Return version and exit
        ```
        
        ### Browsing
        
        Let's consider the following path tree:
        
        ```
        .
        ├── empty
        ├── images
        │   └── knight.png
        ├── index.html
        ├── mdown
        │   └── index.md
        ├── mdown-readme
        │   └── README.md
        └── subdir
            └── index.html
        ```
        
        Here is a table describing the different pages rendered with the given URL in your browser
        
        | URL                | Content                | Content type | Status Code           |
        |:-------------------|:-----------------------|:-------------|:----------------------|
        | /                  | index.html             | text/html    | 200 OK                |
        | /empty             | directory listing      | text/html    | 200 OK                |
        | /images/knight.png | knight.png (as binary) | image/png    | 200 OK                |
        | /mdown/            | index.md (as HTML)     | text/html    | 200 OK                |
        | /mdown/index.md    | index.md (as HTML)     | text/html    | 200 OK                |
        | /mdown-readme      | README.md (as HTML)    | text/html    | 200 OK                |
        | /subdir            | redirect to /subdir/   | -            | 301 MOVED PERMANENTLY |
        | /subdir/           | subdir/index.html      | text/html    | 200 OK                |
        
        ### Indexes
        
        When 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.
        
        If 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.
        
        ### HTTP Verbs
        
        GET & HEAD verbs are implemented.
        
        POST, PUT, DELETE will result into a 405 Method Not Allowed error.
        
        ### Markdown templates
        
        By 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.
        
        We've used various minimalist CSS frameworks for rendering and layout:
        
        * [miligram](https://milligram.io/),
        * [mini css](https://minicss.org/),
        * [Github Markdown CSS](https://github.com/sindresorhus/github-markdown-css),
        
        ### Custom styles
        
        If 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.
        
        Example:
        
        ```sh
        serve-md /path/to/directory --stylesheet ~/my-style.css
        ```
        
        ## Hack
        
        1. Clone this repository.
        2. Write tests.
        3. Implement stuff.
        4. Open a Pull Request.
        
        **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.
        
        ### Run automated tests
        
        In a shell session, run tests with:
        
        ```shell
        make test
        ```
        
Keywords: web static markdown
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Provides-Extra: dev
Provides-Extra: maintain
