{"action":"created","issue":{"url":"https://api.github.com/repos/mkdocs/mkdocs/issues/884","repository_url":"https://api.github.com/repos/mkdocs/mkdocs","labels_url":"https://api.github.com/repos/mkdocs/mkdocs/issues/884/labels{/name}","comments_url":"https://api.github.com/repos/mkdocs/mkdocs/issues/884/comments","events_url":"https://api.github.com/repos/mkdocs/mkdocs/issues/884/events","html_url":"https://github.com/mkdocs/mkdocs/issues/884","id":146028428,"number":884,"title":"Better way to perform pre-processing on source md files / Support a custom directive \"including\" a path-specified file","user":{"login":"ronjouch","id":522085,"avatar_url":"https://avatars.githubusercontent.com/u/522085?v=3","gravatar_id":"","url":"https://api.github.com/users/ronjouch","html_url":"https://github.com/ronjouch","followers_url":"https://api.github.com/users/ronjouch/followers","following_url":"https://api.github.com/users/ronjouch/following{/other_user}","gists_url":"https://api.github.com/users/ronjouch/gists{/gist_id}","starred_url":"https://api.github.com/users/ronjouch/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ronjouch/subscriptions","organizations_url":"https://api.github.com/users/ronjouch/orgs","repos_url":"https://api.github.com/users/ronjouch/repos","events_url":"https://api.github.com/users/ronjouch/events{/privacy}","received_events_url":"https://api.github.com/users/ronjouch/received_events","type":"User","site_admin":false},"labels":[],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":3,"created_at":"2016-04-05T15:42:29Z","updated_at":"2016-04-05T17:38:16Z","closed_at":"2016-04-05T16:01:09Z","body":"Hi.\r\n\r\nI'm working to improve the accessibility of a projects high-level doc (as opposed to docstrings-based per-class/method doc). It's already markdown-based, and I picked mkdocs because it does the job well. So as expected, I'm ending up with a `docs` folder at the root of the project, with a dozen `.md` files.\r\n\r\nHowever, as part of *\"improving the accessibility of high-level doc\"*, we had a goal of bringing the doc as close as possible to the code. So in cases where it makes sense, we want high-level doc to be included directly in the code (c++ in our case) as comments, to minimize eventual doc/code de-synchronization: when the documentation is in your face *in the code*, it's easier to remember updating it when changing code.\r\n\r\nTo my knowledge this is not possible with mkdocs, so I ended up with a simple hackish pre-processing Python script that reads `mkdocs.yml` and, for each `.md` referenced in the `pages` section, looks for something like\r\n\r\n```\r\n!md_include path/to/some.cpp\r\n```\r\n\r\n... opens `path/to/some.cpp`, then finds\r\n\r\n```\r\n/** md\r\nAwesome markdown-based doc on `some.cpp`.\r\n*/\r\n```\r\n\r\n... and replaces the `!md_include` with the contents delimited by the special `/** md` ... `*/` multi-line comment. Pre-processed files are dumped to a temporary folder, from where the script then calls `mkdocs build` and calls it a day. This works well for us, except it's hackish and breaks `mkdocs serve`.\r\n\r\n→ Do you see a better way of reaching the same result with the current mkdocs?  \r\n→ If not, is there interest to add support for such custom pre-processing?"},"comment":{"url":"https://api.github.com/repos/mkdocs/mkdocs/issues/comments/205912699","html_url":"https://github.com/mkdocs/mkdocs/issues/884#issuecomment-205912699","issue_url":"https://api.github.com/repos/mkdocs/mkdocs/issues/884","id":205912699,"user":{"login":"facelessuser","id":1055125,"avatar_url":"https://avatars.githubusercontent.com/u/1055125?v=3","gravatar_id":"","url":"https://api.github.com/users/facelessuser","html_url":"https://github.com/facelessuser","followers_url":"https://api.github.com/users/facelessuser/followers","following_url":"https://api.github.com/users/facelessuser/following{/other_user}","gists_url":"https://api.github.com/users/facelessuser/gists{/gist_id}","starred_url":"https://api.github.com/users/facelessuser/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/facelessuser/subscriptions","organizations_url":"https://api.github.com/users/facelessuser/orgs","repos_url":"https://api.github.com/users/facelessuser/repos","events_url":"https://api.github.com/users/facelessuser/events{/privacy}","received_events_url":"https://api.github.com/users/facelessuser/received_events","type":"User","site_admin":false},"created_at":"2016-04-05T17:38:16Z","updated_at":"2016-04-05T17:38:16Z","body":"@ronjouch You could adapt the markdown-include extension listed in #777 by modifying it to suite your need.  You could have it include your source file(s) and then have the extension filter out the non relevant text leaving you only with your markdown source comments before inserting it into the body of the markdown file.  If that is still not doable, as @waylan said, you would need to wait for the Plugin API listed in #206."}}