{"id":28074297,"url":"https://github.com/gbbirkisson/mkdocs-fun-plugin","last_synced_at":"2025-05-12T23:33:10.166Z","repository":{"id":289667394,"uuid":"972008943","full_name":"gbbirkisson/mkdocs-fun-plugin","owner":"gbbirkisson","description":"Dead simple custom python functions with mkdocs","archived":false,"fork":false,"pushed_at":"2025-05-05T07:02:11.000Z","size":68,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-05T08:22:08.551Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pypi.org/project/mkdocs-fun-plugin","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gbbirkisson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-24T11:55:44.000Z","updated_at":"2025-05-05T07:02:14.000Z","dependencies_parsed_at":"2025-04-24T13:22:58.968Z","dependency_job_id":"c228ba3e-f6b1-48a1-a348-dd8bdc47b174","html_url":"https://github.com/gbbirkisson/mkdocs-fun-plugin","commit_stats":null,"previous_names":["gbbirkisson/mkdocs-fun-plugin"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbbirkisson%2Fmkdocs-fun-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbbirkisson%2Fmkdocs-fun-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbbirkisson%2Fmkdocs-fun-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbbirkisson%2Fmkdocs-fun-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gbbirkisson","download_url":"https://codeload.github.com/gbbirkisson/mkdocs-fun-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253841469,"owners_count":21972656,"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":"2025-05-12T23:33:03.819Z","updated_at":"2025-05-12T23:33:10.154Z","avatar_url":"https://github.com/gbbirkisson.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/gbbirkisson/mkdocs-fun-plugin\"\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/gbbirkisson/mkdocs-fun-plugin/main/logo.png\" alt=\"Logo\" height=\"128\"\u003e\n    \u003c/a\u003e\n    \u003cbr\u003emkdocs-fun-plugin\n  \u003c/p\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Dead simple custom python \u003cb\u003efun\u003c/b\u003ections with \u003cb\u003emkdocs\u003c/b\u003e\n\u003c/p\u003e\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [Usage 📖](#usage-)\n* [Configuration 🎛](#configuration-)\n* [Examples 💡](#examples-)\n  * [References and links](#references-and-links)\n  * [Shell](#shell)\n  * [File contents](#file-contents)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n## Usage 📖\n\nInstall the plugin in your project ...\n\n```bash\npip install mkdocs-fun-plugin\n```\n\n... and add it to your `mkdocs.yaml` configuration ...\n\n```yaml\n# mkdocs.yaml\nplugins:\n  - fun\n```\n\n... create a `docs/fun.py` file ...\n\n```python\n# docs/fun.py\ndef hello() -\u003e str:\n    return \"world\"\n```\n\n... and start using your functions in your docs ...\n\n```markdown\n\u003c!-- docs/docs.md --\u003e\nThis #!hello() comes from my function!\n```\n\n... becomes ...\n\n```markdown\nThis world comes from my function!\n```\n\n## Configuration 🎛\n\nYou can customize the plugin behaviour with configuration:\n\n```yaml\n# mkdocs.yaml\nplugins:\n  - fun:\n      pattern: \"#!(?P\u003cfunc\u003e[^\\(]+)\\((?P\u003cparams\u003e[^\\)]*)\\)\"  # Regex to match functions\n      module: fun.py  # Python file that defines your functions\n```\n\n## Examples 💡\n\n### References and links\n\n```python\n# docs/fun.py\ndef ref(key: str) -\u003e str:\n    \"\"\"\n    Bookkeeping and standardized format of references in the docs\n    \"\"\"\n\n    r = {\n        \"mcguffin\": (\"McGuffin\", \"/refs/mcguffin.md\"),\n    }.get(key)\n    assert r, f\"No ref for '{key}' found\"\n    return f\"[`{r[0]}`]({r[1]})\"\n\ndef link(key: str) -\u003e str:\n    \"\"\"\n    Bookkeeping and standardized format of external links in the docs\n    \"\"\"\n\n    l = {\n        \"github\": (\":fontawesome-brands-github: Github\", \"https://www.github.com\"),\n    }.get(key)\n    assert l, f\"No link for '{key}' found\"\n    return f'[{l[0]}]({l[1]}){{:target=\"_blank\"}}'\n```\n\n```markdown\n\u003c!-- docs/docs.md --\u003e\nLook at our internal #!ref(mcguffin) docs for more info. Also open up #!link(github).\n```\n\n... becomes ...\n\n```markdown\nLook at our internal [`McGuffin`](/refs/mcguffin.md) docs for more info. Also open up [:fontawesome-brands-github: Github](https://www.github.com){:target=\"_blank\"}.\n```\n\n### Shell\n\n```python\n# docs/fun.py\n@functools.cache\ndef shell(cmd: str) -\u003e str:\n    \"\"\"\n    Run arbitrary commands and return stdout\n    \"\"\"\n\n    return (\n        subprocess.run(\n            cmd,\n            shell=True,\n            check=True,\n            capture_output=True,\n        )\n        .stdout.decode()\n        .strip()\n    )\n```\n\n```markdown\n\u003c!-- docs/docs.md --\u003e\n#!shell(\"echo hello | cowsay\")\n```\n\n... becomes ...\n\n```markdown\n_______\n\u003c hello \u003e\n -------\n        \\   ^__^\n         \\  (oo)\\_______\n            (__)\\       )\\/\\\n                ||----w |\n                ||     ||\n```\n\n### File contents\n\n```python\n# docs/fun.py\ndef func_def(file: str, name: str) -\u003e str:\n    \"\"\"\n    Reads 'file' and returns the definition of function 'name'\n    \"\"\"\n\n    with (pathlib.Path(__file__).parent / file).open() as f:\n        content = f.read()\n\n    # Find function definition including decorators\n    pattern = rf\"(@.*\\n)*def {name}\\s*\\([^)]*\\)[^:]*:\"\n    match = re.search(pattern, content, re.MULTILINE)\n    assert match, f\"Function '{name}' not found in '{file}'\"\n\n    # Find where function starts and ends\n    start_pos = match.start()\n    lines = content.splitlines()\n    start_line = content[:start_pos].count(\"\\n\")\n\n    # Find function body by tracking indentation\n    function_lines = [lines[start_line]]\n    indent = (\n        re.match(r\"(\\s*)\", lines[start_line + 1]).group(1)\n        if start_line + 1 \u003c len(lines)\n        else \"\"\n    )\n\n    # Collect and return\n    for i in range(start_line + 1, len(lines)):\n        line = lines[i]\n        if line.strip() and not line.startswith(indent):\n            break\n        function_lines.append(line)\n    return \"\\n\".join(function_lines).strip()\n```\n\n```markdown\n\u003c!-- docs/docs.md --\u003e\n#!func_def(fun.py, hello)\n```\n\n... becomes ...\n\n```markdown\ndef hello() -\u003e str:\n    return \"world\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbbirkisson%2Fmkdocs-fun-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgbbirkisson%2Fmkdocs-fun-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbbirkisson%2Fmkdocs-fun-plugin/lists"}