{"id":18068612,"url":"https://github.com/sondregronas/turtleconverter","last_synced_at":"2025-04-05T16:13:56.885Z","repository":{"id":243067860,"uuid":"811377334","full_name":"sondregronas/turtleconverter","owner":"sondregronas","description":"A markdown to HTML converter using mkdocs","archived":false,"fork":false,"pushed_at":"2024-12-06T10:03:03.000Z","size":499,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-11T12:47:58.431Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://sondregronas.github.io/turtleconverter/","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/sondregronas.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-06T13:32:13.000Z","updated_at":"2024-12-06T10:03:07.000Z","dependencies_parsed_at":"2024-06-06T15:09:46.435Z","dependency_job_id":"9acb2fbf-f50f-4ea8-8727-c3c728214991","html_url":"https://github.com/sondregronas/turtleconverter","commit_stats":null,"previous_names":["sondregronas/turtleconverter"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sondregronas%2Fturtleconverter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sondregronas%2Fturtleconverter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sondregronas%2Fturtleconverter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sondregronas%2Fturtleconverter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sondregronas","download_url":"https://codeload.github.com/sondregronas/turtleconverter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247361702,"owners_count":20926643,"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":[],"created_at":"2024-10-31T08:07:11.918Z","updated_at":"2025-04-05T16:13:56.855Z","avatar_url":"https://github.com/sondregronas.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐢 TurtleConverter 🐢\n\n[![GitHub Pages](https://badgen.net/badge/example%20output/github%20pages/?icon=chrome)](https://sondregronas.github.io/turtleconverter/)\n\nA ~~slow and inefficient~~ converter for markdown to HTML. This is a very hacky way to use [mkdocs](https://www.mkdocs.org/)\nto convert markdown files to HTML. It works by overriding the `_build` function of mkdocs to hook in a markdown file to\nthen extract the HTML from said markdown file. The header, nav and footer is omitted from the output.\n\n## Installation\n\nThe package is not on PyPi, so you will have to install it from the git repository.\n\n```bash\npip install git+https://github.com/sondregronas/turtleconverter@main\n```\n\n## Usage\n\n```py\nfrom turtleconverter import mdfile_to_sections, mdfile_to_html, generate_static_files\n\n# def generate_static_files(static_folder: Path = Path('static'), assets_folder: Path = Path('turtleconvert')) -\u003e None:\ngenerate_static_files()\n# Generates the static files (CSS, JS, etc.) in a \"static/assets/\" folder (paths must match with the other functions)\n\n\n# def mdfile_to_html(md_file_path: Path, static_folder: Path = Path('static'),\n#                    assets_folder: Path = Path('turtleconvert'), include_metadata: bool = False,\n#                    abspath: bool = True, template: Path = 'turtleconvert.html',\n#                    generate_static_files: bool = False) -\u003e str or tuple:\n\n# Converts a markdown file to HTML\nhtml = mdfile_to_html(\"test.md\")\nprint(html)\n# A complete HTML file with the contents of the markdown file (note that the static files are not generated by default)\n# The static folders / assets folders must match those used in the generate_static_files function\n\n\n# def mdfile_to_sections(md_file_path: Path, static_folder: Path = Path('static'),\n#                        assets_folder: Path = Path('turtleconvert'), remove_heading: bool = True,\n#                        abspath: bool = True, template: Path = 'turtleconvert.html',\n#                        generate_static_files: bool = False) -\u003e dict:\n\n# Converts a markdown file to sections\nsections = mdfile_to_sections(\"test.md\")\nprint(sections)\n# {\n#    \"heading\": \"My Markdown File!\",\n#    \"head\": \"\u003cEverything inside of the head tag\u003e\",\n#    \"body\": \"\u003cEverything inside of the body tag (excluding the heading unless remove_heading=False)\u003e\",\n#    \"meta\": { \u003cAll the metadata (frontmatter) from the markdown file as a dictionary\u003e }\n# }\n# The static folders / assets folders must match those used in the generate_static_files function\n```\n\nExceptions will raise a `turtleconverter.ConversionError` with a copy of the error message.\n\nSections is useful if you want to include the markdown file in a template, and want to separate the head and body of the\nfile.\n\nYou can also use the partial library to create your partial functions with different static folders for easier use\n\n```py\nfrom turtleconverter import mdfile_to_sections, generate_static_files\nfrom functools import partial\n\nmy_partial_function = partial(mdfile_to_sections, static_folder=Path('a_different_static_folder'),\n                              assets_folder=Path('a_different_assets_folder'))\n\ngenerate_static_files(Path('a_different_static_folder'), Path('a_different_assets_folder'))\nresult = my_partial_function('test.md')\n```\n\n## Overrides folder\n\nFeel free to fork \u0026 change the `overrides` folder or `mkdocs.yml` file to customize the template - you can add as many\nmkdocs plugins as you want, as long as they are added to the pyproject.toml file before installing the package.\n\nNote: the color palette are defined by the script in the `theme_switch_on_load` block, by default it's set to `blue`.\n\n## Custom Template for HTML rendering\n\nYou may also pass a custom template to the renderer by passing them to the function as an argument like so:\n\n```py\nhtml = mdfile_to_html(\"test.md\", template=\"custom_template.html\")  # alternatively you can use a Path object\n```\n\n[example_override.html](example_override.html) is an example of a custom template that can be used during conversion, *\n*\u003cins\u003ethough creating your own with jinja2 using the results from `mdfile_to_sections()` is the projects intended\nusecase\u003c/ins\u003e**. Note that mkdocs will always generate a h1 tag with the title of the markdown file, so you should not\ninclude a h1 tag in your custom template.\n\n## Issues\n\n- Image paths remain relative to the markdown file - **this script does not move/copy any images!!**\n- Exceptions are not handled very well, and might break some things due to capturing _everything_ (`except Exception`)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsondregronas%2Fturtleconverter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsondregronas%2Fturtleconverter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsondregronas%2Fturtleconverter/lists"}