search

JuliaDocs / Documenter.jl

A documentation generator for Julia.
https://documenter.juliadocs.org
MIT License
807 stars 476 forks source link

Integrating Documenter with parsers for non-markdown documents #1074

Open non-Jedi opened 5 years ago

non-Jedi commented 5 years ago

Related issue: #821.

I've started writing a basic parser for org-mode syntax and am wondering what the best way of integrating it with Documenter would be. Looking through the unfamiliar codebase, would my best bet be to implement Base.convert(Documenter.Utilities.Markdown2.MD, ::Org.Document)? The problem then is that I would still need to override the Documents.Page constructor. I could keep going down this path, but I'd basically just be trying to shoe-horn things into an architecture that's not currently well-built as far as I can see for multiple document parsers.

Any thoughts on the changes that would be necessary on the Documenter end for this to work? Or an alternative approach for integration on my end that wouldn't require Documenter changes?

mortenpi commented 5 years ago

I have a branch that extends #552 which provides an interface for this kind of thing (mp/external-pages). Essentially, you have to provide a parser function that goes ::String -> Markdown.MD. You can see an example invocation here. That particular parser comes from CMark.jl.

I would encourage you to try out that branch and let me know if it works. I want to turn that into a proper feature in the near-ish future and feedback would definitely help. You just have to be able to convert your docs to the standard Markdown.MD trees.

CiaranOMara commented 4 years ago

I too am interested in those external pages.