{"id":18107076,"url":"https://github.com/elboletaire/docs-cake-plugin","last_synced_at":"2025-03-29T13:31:44.351Z","repository":{"id":19974112,"uuid":"23241169","full_name":"elboletaire/docs-cake-plugin","owner":"elboletaire","description":":cake: A simple CakePHP plugin that parses/renders markdown files","archived":true,"fork":false,"pushed_at":"2016-02-26T10:26:16.000Z","size":18,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-13T17:35:32.069Z","etag":null,"topics":["cakephp","cakephp-plugin","documentation","markdown","markdown-parser","plugin"],"latest_commit_sha":null,"homepage":"","language":"CSS","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/elboletaire.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":null,"security":null,"support":null}},"created_at":"2014-08-22T21:57:32.000Z","updated_at":"2025-02-02T16:56:55.000Z","dependencies_parsed_at":"2022-07-22T07:49:58.242Z","dependency_job_id":null,"html_url":"https://github.com/elboletaire/docs-cake-plugin","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elboletaire%2Fdocs-cake-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elboletaire%2Fdocs-cake-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elboletaire%2Fdocs-cake-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elboletaire%2Fdocs-cake-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elboletaire","download_url":"https://codeload.github.com/elboletaire/docs-cake-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246190468,"owners_count":20738035,"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":["cakephp","cakephp-plugin","documentation","markdown","markdown-parser","plugin"],"created_at":"2024-10-31T23:09:12.636Z","updated_at":"2025-03-29T13:31:43.995Z","avatar_url":"https://github.com/elboletaire.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cake 1.3 Docs/Markdown plugin\n\nThis CakePHP plugin basically renders markdown files using the github api.\n\nUse it to show help pages or to easily document your projects and make the info\navailable to the final client directly from the app.\n\nAnd everything only writing markdown files!\n\n## Installation\n\nAs a git submodule:\n\n```bash\ngit submodule add https://github.com/elboletaire/docs-cake-plugin.git app/plugins/docs\n```\n\n## Kick-starting the plugin\n\nYou only need to define the docs path constant (`DOCS_PATH`) in order to use\nthis plugin.\n\nTo do so, on your `boostrap.php` file put this line:\n\n```php\ndefine('DOCS_PATH', '/path/to/your/markdown/files');\n```\n\n## Usage\n\nBy default this plugin searches for a `readme.md` file. So, if your folder does\nnot have that file, it will return an `error404`.\n\nAs this plugin does not have any route defined you'll need to access them using\nthe default cakePHP fallbacks:\n\n- `/docs` should render `DOCS_PATH/readme.md`.\n- `/admin/docs` should render `DOCS_PATH/readme.md`.\n- `/docs/docs/view/anyother.md` should render `DOCS_PATH/anyother.md`.\n- `/docs/docs/view/path/to/md/woha.md` should render `DOCS_PATH/path/to/md/woha.md`.\n\nYou can access directly `/docs` because the `view()` method has two aliases:\n`index()` and `admin_index()`.\n\nBTW, I recommend you creating your custom route:\n\n```php\nRouter::connect('/admin/docs/*', array(\n\t'controller' =\u003e 'docs',\n\t'action'     =\u003e 'index',\n\t'plugin'     =\u003e 'docs',\n\t'admin'      =\u003e true\n));\n```\n\n### Custom usage\n\nIf you would like just to render markdown files, you can do so using the\nMarkdownComponent given with this plugin.\n\n```php\n// Your Controller or Component\npublic $components = array(\n\t'Docs.Markdown'\n);\n```\n\nIt has many options making it very flexible:\n\n```php\npublic $components = array(\n\t'Docs.Markdown' =\u003e array(\n        'base_path'          =\u003e DOCS_PATH,\n        'cache'              =\u003e 'default',\n        'layout'             =\u003e '/layouts/github',\n        'remove_uc_prefixes' =\u003e true,\n        'on_post_process'    =\u003e false,\n        'on_pre_process'     =\u003e false,\n        'replace_base_url'   =\u003e array(\n            'controller' =\u003e 'docs',\n            'action'     =\u003e 'index',\n            'plugin'     =\u003e 'docs'\n        )\n\t)\n);\n```\n\n- `base_path`: By defaults points to `DOCS_PATH`. It should be an absolute path,\n  but maybe you can try with relative paths too (relative to `WWW_ROOT`,\n  obviously).\n- `cache`: whether or not to enable the cache. To enable it specify a cache\n  configuration key (by default enabled using default cache).\n- `layout`: the layout to use when rendering markdowns using the `render()`\n  method.\n- `remove_uc_prefixes`: remove `user-content-` prefixes from resulting HTML.\n- `on_pre_process`: callback used before processing the markdown file. It takes\n  one argument: `$markdown` and your callback must return it (modified).\n- `on_post_process`: same as `on_pre_process` but called after the markdown file\n  has been rendered into a HTML file. Here is where `remove_uc_prefixes` take\n  effect.\n- `replace_base_url`: the url path to be prefixed to relative links. Set it to\n  false to not replace relative links.\n\nAn example usage could be:\n\n```php\npublic $components = array(\n\t'Docs.Markdown' =\u003e array(\n\t\t// disable some default settings so we get the original github version\n\t\t'replace_base_url'   =\u003e false,\n\t\t'remove_uc_prefixes' =\u003e false\n\t)\n);\n\npublic function admin_add()\n{\n\tif (!empty($this-\u003edata)) {\n\t\t$this-\u003eMyModel-\u003eset($this-\u003edata);\n\t\tif ($this-\u003eMyModel-\u003evalidates()) {\n\t\t\t// Render a markdown to store it into the DB\n\t\t\t$this-\u003edata['MyModel']['parsed'] = $this-\u003eMarkdown-\u003erenderMarkdown($this-\u003edata['MyModel']['markdown']);\n\n\t\t\tif ($this-\u003eMyModel-\u003esave($this-\u003edata)) {\n\t\t\t\t// Whatever\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n## TODO\n\n- Version for CakePHP 2.X/3.X\n- Add non-API renderer (and set it as option)\n- More templates\n\n## License\n\nCopyright 2014 Òscar Casajuana (a.k.a. elboletaire)\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felboletaire%2Fdocs-cake-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felboletaire%2Fdocs-cake-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felboletaire%2Fdocs-cake-plugin/lists"}