# markdownserver
[](https://pypi.python.org/pypi/yhttp-markdown)
[](https://github.com/yhttp/markdown/actions/workflows/build.yml)
[](https://coveralls.io/github/yhttp/markdown?branch=master)
[](https://python.org)
Markdown server using yhttp.
## Features
- Serve a directory of markdown files and subdirectories as HTML using
[markdown2](https://github.com/trentm/python-markdown2).
- Personalizable favicon, touch-icon logo and etc.
- Syntaxt highlighting for code blocks + themes using
[pygment](https://pygments.org/).
- Copy-to-clipboard buttons for code-blocks and HTML bookmarks.
- Resizable sidebar and page layout powered by CSS Flexbox.
- Breadcrumbs (path) navigator.
- Change configuration using file and command line interface.
- [mermaid](https://mermaid.js.org/) support.
## Install
```bash
pip install yhttp-markdown
```
## Quickstart
Navigate to a directory consist of markdown files, then:
```bash
yhttp-markdown serve
```
## Command line interface
```bash
yhttp-markdown --help
```
```bash
usage: yhttp-markdown [-h] [-c FILE] [-C DIRECTORY] [-O OPTION] [--version]
{serve,s,completion} ...
options:
-h, --help show this help message and exit
-c FILE, --configuration-file FILE
Configuration file
-C DIRECTORY, --directory DIRECTORY
Change to this path before starting, default is: `.`
-O OPTION, --option OPTION
Set a configutation entry: -O foo.bar.baz='qux'. this
argument can passed multiple times.
--version
Sub commands:
{serve,s,completion}
serve (s)
completion Bash auto completion using argcomplete python package.
```
### Bash auto completion
To enable bash auto comletion, first run this command:
```bash
yhttp-markdown completion install
```
Then close and re-open your shell or deactivate/activate the current virtual
environment (if using) to apply the change:
```bash
deactivate && . activate.sh
```
Test it:
```bash
yhttp-markdown TAB TAB
```
## Configuration
`yhttp-markdown` can be configured using a YAML configuration file
(the `-c/--configuration-file`) and `-O/--option` flags at the same time:
```bash
yhttp-markdown -c settings.yaml -O highlight.theme=vim -O toc.depth=2 serve
```
### Configuration file
This is the example of default configuration file:
```yaml
# settings.yaml
# app specific
default: index.md
root: .
# site title
title: HTTP Markdown Server
# table of contents
toc:
depth: 3
# a list of regex patterns to exclude from TOC and HTTP serve
exclude:
# metadata path
metadata:
physical: .ymdmetadata
baseurl: /.ymdmetadata
# syntaxt highlighting theme
highlight:
theme: monokai
```
### Root directory
By default, `yhttp-markdown` serves files from the current directory (`pwd`).
you may navigate to desired path before running the `yhttp-markdown` command
or set the `root` configuration entry:
```yaml
# settings.yaml
root: path/to/www/root
```
```bash
yhttp-markdown -O root=/path/to/www/root serve
```
You may also use the `-C/--directory` command line option to `cd` to a
directory before running the server.
```bash
yhttp-markdown -C /path/to/www/root serve
```
### Default document
`yhttp-markdown` looks for the `index.md` on requests referring to a
directory (http://example.com/foo/). but, this can be changed using the
`default` configuration entry:
```yaml
# settings.yaml
default: default.md
```
Or, using the command line interface:
```bash
yhttp-markdown -O default=default.md serve
```
### Table of contents
`yhttp-markdown` crawls the `*.md` files and finds the markdown headdings:
```markdown
# Header 1
## Header 2
### Header 3
#### Header 4
##### Header 5
###### Header 6
```
To genrate a tree of HTTP bookmarks and table of contents section of the
current requested path.
You can change the `toc.depth` configuration value to change the behaviour:
```bash
yhttp-markdown -Otoc.depth=3 serve
```
### Exclusion
To exclude file and directories from serving use the `exclude` configuration
entry. it's a collection of regular expression patterns relative to the sites
root (`/`):
```yaml
# settings.yaml
exclude:
- foo\\.md
- bar/?.*
```
Or, using the command line interface:
```bash
yhttp-markdown -O"exclude=[lorem\.md, bar/?.*]" serve
```
### Site metadata
The default website metadata such as `favicon` and `logo` could be overriden
using the `.ymdmetadata` directory. this directory must be placed dirctly
inside the `root`. so, these resources will be available at
`http://localhost:8080/.ymdmetadata/` when the server is running.
This is an examples of the metadata directory.
```
.ymdmetadata/
android-chrome-192x192.png
android-chrome-512x512.png
apple-touch-icon.png
favicon-16x16.png
favicon-32x32.png
favicon.ico
logo.svg
```
The name and base path are also changable using the `metadata.physical` and
`metadata.baseurl` configuration entries:
```yaml
# settings.yaml
metadata:
physical: .ymdmetadata
baseurl: /.ymdmetadata
```
### Code blocks syntax highlighting
`yhttp-markdown` uses the
[fenced-code-blocks](https://github.com/trentm/python-markdown2/wiki/fenced-code-blocks)
and [pygment](https://pygments.org/) to make the code blocks prettier.
The pygment theme can be changed using the `highlight.theme` configuration
entry:
```yaml
# settings.yaml
highlight:
theme: monokai
```
Or, using the command line interface:
```bash
yhttp-markdown -O highlight.theme=vim serve
```
Available themes:
- autumn
- borland
- bw
- colorful
- default
- emacs
- friendly
- fruity
- manni
- monokai
- murphy
- native
- pastie
- perldoc
- tango
- trac
- vim
- vs
See [pygments styles page](https://pygments.org/styles/) to figure out how
they looks like.
## Contribuition
### Setup development environment
Install [python-makelib](https://github.com/pylover/python-makelib), then:
```bash
cd path/to/yhttp-markdown
make fresh env activate.sh
```
### Test and coverage
```bash
make test
make cover
```
### Lint
```bash
make lint
```
### Serve
```bash
make serve
```
Or
```bash
source activate.sh
yhttp-markdown -C examples serve
```
> **_NOTE:_** Do a `make qa` or `make cover lint` before commit.
Raw data
{
"_id": null,
"home_page": "https://github.com/yhttp/markdown",
"name": "yhttp-markdown",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Vahid Mardani",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/45/aa/734ec2f8fd174f3411e29018780d1111a1421b7c77be2613e6ed9b62813e/yhttp_markdown-1.0.2.tar.gz",
"platform": null,
"description": "# markdownserver\n[](https://pypi.python.org/pypi/yhttp-markdown)\n[](https://github.com/yhttp/markdown/actions/workflows/build.yml)\n[](https://coveralls.io/github/yhttp/markdown?branch=master)\n[](https://python.org)\n\nMarkdown server using yhttp.\n\n\n## Features\n\n- Serve a directory of markdown files and subdirectories as HTML using\n [markdown2](https://github.com/trentm/python-markdown2).\n- Personalizable favicon, touch-icon logo and etc.\n- Syntaxt highlighting for code blocks + themes using\n [pygment](https://pygments.org/).\n- Copy-to-clipboard buttons for code-blocks and HTML bookmarks.\n- Resizable sidebar and page layout powered by CSS Flexbox.\n- Breadcrumbs (path) navigator.\n- Change configuration using file and command line interface.\n- [mermaid](https://mermaid.js.org/) support.\n\n\n\n\n\n## Install\n```bash\npip install yhttp-markdown\n```\n\n## Quickstart\nNavigate to a directory consist of markdown files, then:\n```bash\nyhttp-markdown serve\n```\n\n## Command line interface\n```bash\nyhttp-markdown --help\n```\n\n```bash\nusage: yhttp-markdown [-h] [-c FILE] [-C DIRECTORY] [-O OPTION] [--version]\n {serve,s,completion} ...\n\noptions:\n -h, --help show this help message and exit\n -c FILE, --configuration-file FILE\n Configuration file\n -C DIRECTORY, --directory DIRECTORY\n Change to this path before starting, default is: `.`\n -O OPTION, --option OPTION\n Set a configutation entry: -O foo.bar.baz='qux'. this\n argument can passed multiple times.\n --version\n\nSub commands:\n {serve,s,completion}\n serve (s)\n completion Bash auto completion using argcomplete python package.\n```\n\n### Bash auto completion \nTo enable bash auto comletion, first run this command:\n```bash\nyhttp-markdown completion install\n```\n\nThen close and re-open your shell or deactivate/activate the current virtual\nenvironment (if using) to apply the change:\n```bash\ndeactivate && . activate.sh\n```\n\nTest it:\n```bash\nyhttp-markdown TAB TAB\n```\n\n\n## Configuration\n\n`yhttp-markdown` can be configured using a YAML configuration file \n(the `-c/--configuration-file`) and `-O/--option` flags at the same time:\n\n```bash\nyhttp-markdown -c settings.yaml -O highlight.theme=vim -O toc.depth=2 serve\n```\n\n### Configuration file\nThis is the example of default configuration file:\n\n```yaml\n# settings.yaml\n\n\n# app specific\ndefault: index.md\nroot: .\n\n\n# site title\ntitle: HTTP Markdown Server\n\n\n# table of contents\ntoc:\n depth: 3\n\n\n# a list of regex patterns to exclude from TOC and HTTP serve\nexclude:\n\n\n# metadata path\nmetadata:\n physical: .ymdmetadata\n baseurl: /.ymdmetadata\n\n\n# syntaxt highlighting theme\nhighlight:\n theme: monokai\n```\n\n\n### Root directory\nBy default, `yhttp-markdown` serves files from the current directory (`pwd`).\nyou may navigate to desired path before running the `yhttp-markdown` command\nor set the `root` configuration entry:\n\n```yaml\n# settings.yaml\n\nroot: path/to/www/root\n```\n\n```bash\nyhttp-markdown -O root=/path/to/www/root serve\n```\n\n\nYou may also use the `-C/--directory` command line option to `cd` to a \ndirectory before running the server.\n```bash\nyhttp-markdown -C /path/to/www/root serve\n```\n\n### Default document\n`yhttp-markdown` looks for the `index.md` on requests referring to a \ndirectory (http://example.com/foo/). but, this can be changed using the \n`default` configuration entry:\n\n```yaml\n# settings.yaml\n\ndefault: default.md\n```\n\nOr, using the command line interface:\n```bash\nyhttp-markdown -O default=default.md serve\n```\n\n\n### Table of contents\n`yhttp-markdown` crawls the `*.md` files and finds the markdown headdings:\n\n```markdown\n# Header 1\n## Header 2\n### Header 3\n#### Header 4\n##### Header 5\n###### Header 6\n```\n\nTo genrate a tree of HTTP bookmarks and table of contents section of the \ncurrent requested path.\n\nYou can change the `toc.depth` configuration value to change the behaviour:\n```bash\nyhttp-markdown -Otoc.depth=3 serve\n```\n\n\n### Exclusion\nTo exclude file and directories from serving use the `exclude` configuration \nentry. it's a collection of regular expression patterns relative to the sites\nroot (`/`):\n\n```yaml\n# settings.yaml\n\nexclude:\n - foo\\\\.md\n - bar/?.*\n```\n\nOr, using the command line interface:\n```bash\nyhttp-markdown -O\"exclude=[lorem\\.md, bar/?.*]\" serve\n```\n\n\n### Site metadata\nThe default website metadata such as `favicon` and `logo` could be overriden \nusing the `.ymdmetadata` directory. this directory must be placed dirctly \ninside the `root`. so, these resources will be available at \n`http://localhost:8080/.ymdmetadata/` when the server is running.\n\nThis is an examples of the metadata directory.\n```\n.ymdmetadata/\n android-chrome-192x192.png\n android-chrome-512x512.png\n apple-touch-icon.png\n favicon-16x16.png\n favicon-32x32.png\n favicon.ico\n logo.svg\n```\n\nThe name and base path are also changable using the `metadata.physical` and\n`metadata.baseurl` configuration entries:\n```yaml\n# settings.yaml\n\nmetadata:\n physical: .ymdmetadata\n baseurl: /.ymdmetadata\n```\n\n\n### Code blocks syntax highlighting\n`yhttp-markdown` uses the\n[fenced-code-blocks](https://github.com/trentm/python-markdown2/wiki/fenced-code-blocks)\nand [pygment](https://pygments.org/) to make the code blocks prettier.\n\nThe pygment theme can be changed using the `highlight.theme` configuration\nentry:\n\n```yaml\n# settings.yaml\n\nhighlight:\n theme: monokai\n```\n\nOr, using the command line interface:\n```bash\nyhttp-markdown -O highlight.theme=vim serve\n```\n\nAvailable themes: \n\n- autumn\n- borland\n- bw\n- colorful\n- default\n- emacs\n- friendly\n- fruity\n- manni\n- monokai\n- murphy\n- native\n- pastie\n- perldoc\n- tango\n- trac\n- vim\n- vs\n\nSee [pygments styles page](https://pygments.org/styles/) to figure out how \nthey looks like.\n\n\n## Contribuition\n\n### Setup development environment\n\nInstall [python-makelib](https://github.com/pylover/python-makelib), then:\n```bash\ncd path/to/yhttp-markdown\nmake fresh env activate.sh\n```\n\n### Test and coverage\n```bash\nmake test\nmake cover\n```\n\n### Lint\n```bash\nmake lint\n```\n\n\n### Serve\n```bash\nmake serve\n```\n\nOr\n```bash\nsource activate.sh\nyhttp-markdown -C examples serve\n```\n\n\n> **_NOTE:_** Do a `make qa` or `make cover lint` before commit.\n",
"bugtrack_url": null,
"license": "APLv1",
"summary": "Markdown to HTML coverter and server with yhttp.",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/yhttp/markdown"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5417d21e90bb2daf5a4a6eeec0f09c827ded8ecf26e9e5f159ae06cb0fd1897c",
"md5": "17a16ac5ccfd296caeef66386f5fb251",
"sha256": "8ff67ea9dab35f704776eb981b86e0a52e62813cb2591d7d0b4843ef0515da6d"
},
"downloads": -1,
"filename": "yhttp_markdown-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "17a16ac5ccfd296caeef66386f5fb251",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 360535,
"upload_time": "2024-09-01T15:01:59",
"upload_time_iso_8601": "2024-09-01T15:01:59.289771Z",
"url": "https://files.pythonhosted.org/packages/54/17/d21e90bb2daf5a4a6eeec0f09c827ded8ecf26e9e5f159ae06cb0fd1897c/yhttp_markdown-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "45aa734ec2f8fd174f3411e29018780d1111a1421b7c77be2613e6ed9b62813e",
"md5": "929f7072d37da22716e76957e3778c70",
"sha256": "eff4184b021167426541fbb414dc6d1853194b16e94a02b4ddb5ed349b698e40"
},
"downloads": -1,
"filename": "yhttp_markdown-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "929f7072d37da22716e76957e3778c70",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 347438,
"upload_time": "2024-09-01T15:02:01",
"upload_time_iso_8601": "2024-09-01T15:02:01.333590Z",
"url": "https://files.pythonhosted.org/packages/45/aa/734ec2f8fd174f3411e29018780d1111a1421b7c77be2613e6ed9b62813e/yhttp_markdown-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-01 15:02:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yhttp",
"github_project": "markdown",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "yhttp-markdown"
}
JSON
