{"id":18257923,"url":"https://github.com/linkdd/doceaser","last_synced_at":"2025-10-24T17:05:21.509Z","repository":{"id":233118873,"uuid":"786087725","full_name":"linkdd/doceaser","owner":"linkdd","description":"Interactive documentation with Markdown and HTMX made easier","archived":false,"fork":false,"pushed_at":"2024-04-13T11:48:31.000Z","size":139,"stargazers_count":40,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-20T17:05:21.710Z","etag":null,"topics":["documentation","htmx","markdown","python"],"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/linkdd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","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}},"created_at":"2024-04-13T11:44:57.000Z","updated_at":"2024-10-15T23:14:55.000Z","dependencies_parsed_at":"2024-04-14T01:14:34.844Z","dependency_job_id":"83d20d0c-2028-4195-b079-20bc9cc0e3e0","html_url":"https://github.com/linkdd/doceaser","commit_stats":null,"previous_names":["linkdd/doceaser"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkdd%2Fdoceaser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkdd%2Fdoceaser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkdd%2Fdoceaser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linkdd%2Fdoceaser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linkdd","download_url":"https://codeload.github.com/linkdd/doceaser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247229381,"owners_count":20905040,"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","htmx","markdown","python"],"created_at":"2024-11-05T10:28:09.282Z","updated_at":"2025-10-24T17:05:16.471Z","avatar_url":"https://github.com/linkdd.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# DocEaser\n\nDynamic Interactive documentation made easier.\n\n## Introduction\n\nDocEaser is a very simple framework used to render Markdown documents. The twist\nis that those documents can embed HTMX components written in Python, to add\ninteractivity to your documentation.\n\n## Installation\n\n```shell\n$ pip install git+https://github.com/linkdd/doceaser\n```\n\n## Usage\n\n### Run the server\n\nCreate a folder for your content:\n\n```shell\n$ mkdir content/\n$ mkdir content/_static\n$ python -m doceaser.cli --root content/\nListening on http://localhost:8080/\n```\n\nThe server is based on the production-ready WSGI server\n[waitress](https://docs.pylonsproject.org/projects/waitress/en/latest/).\n\n### Organizing your content\n\nStatic files go in the `content/_static/` directory and will be served at\n`/_static/...` URLs:\n\n| Content path | URL |\n| --- | --- |\n| `content/_static/screenshot.png` | `/_static/screenshot.png` |\n\nHTMX components go in the `content/` directory as Python files, and will be\nserved at `/_components/...` URLs:\n\n| Content path | URL |\n| --- | --- |\n| `content/form.py` | `/_components/form` |\n| `content/hello/world.py` | `/_components/hello/world` |\n\nMarkdown files go in the `content/` directory, and will be served at `/...`\nURLs. The special file `_index.md` can be used as an index section:\n\n| Content path | URL |\n| --- | --- |\n| `content/about.md` | `/about` |\n| `content/_index.md` | `/` |\n| `content/about/_index.md` | `/about` |\n| `content/about/legal.md` | `/about/legal` |\n\n### Writing Markdown files\n\nMarkdown files may have a *frontmatter* header (using YAML, TOML or JSON):\n\n```markdown\n---\ntitle: Hello world\n---\n\n# Hello World\n```\n\nThe `title` property will be used for the `\u003ctitle/\u003e` HTML tag.\n\nTo embed an HTMX component, you can use this special syntax (an extension of\nthe [CommonMark](https://spec.commonmark.org/0.30/) specification):\n\n```markdown\n{\u003c htmx:form \u003e}\n\n{\u003c htmx:hello/world \u003e}\n```\n\nThis will render to the following HTML (with some extra irrelevant details):\n\n```html\n\u003cdiv hx-get=\"/_components/form\" hx-trigger=\"load\"\u003e\u003c/div\u003e\n\n\u003cdiv hx-get=\"/_components/hello/world\" hx-trigger=\"load\"\u003e\u003c/div\u003e\n```\n\n### Writing HTMX components\n\nAn HTMX component is a Python file in the `content/` directory.\nThis file may implement a function per HTTP method to handle the request. That\nfunction accepts a [werkzeug](https://werkzeug.palletsprojects.com/) Request and\nreturns a *werkzeug* Response:\n\n```python\nfrom werkzeug.wrappers import Request, Response\nfrom http import HTTPStatus\n\nfrom lxml.html.builder import E as e\nfrom lxml import html\n\nimport requests\n\n\ndef get(request):\n    r = requests.get(\"https://httpbin.org/anything\")\n    body = e.pre(e.code(r.text))\n\n    return Response(\n        html.tostring(body),\n        status=HTTPStatus.OK,\n        content_type=\"text/html; charset=utf-8\",\n    )\n```\n\n**NB:**\n\n - You can use any method you like to render the HTML. Internally, DocEaser uses\n   `lxml`, so you might as well use it. But it is not mandatory.\n - Any extra Python dependencies you might want shall be installed by you (like\n   `requests` in the example above).\n\n## Documentation\n\nNone at the moment except this README and a few examples in the `examples/`\ndirectory.\n\n## Roadmap\n\nThis project is mostly a Proof of Concept. Nothing has been planned ahead (yet).\nI will probably not actively develop it, but I can at least guarantee that bugs\nwill be addressed, and feature requests will be discussed (and maybe\nimplemented?).\n\nHere are a few ideas that might be nice, from the top of my head:\n\n - **Make the website layout customizable:** At the moment, I simply generate a\n   single page with [Bulma](https://bulma.io) as the CSS framework, everything\n   is tightly coupled to it (fine for a PoC, not ideal for a finished product)\n - **Cache the Markdown rendering:** Everything is rerendered from scratch on\n   every call. This might not be the best for performance.\n\nAny other ideas, and Pull Requests are more than welcome! Give a look to the\n[CONTRIBUTING](./CONTRIBUTING.md) file.\n\n## License\n\nThis software is released under the terms of the [MIT License](./LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinkdd%2Fdoceaser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinkdd%2Fdoceaser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinkdd%2Fdoceaser/lists"}