Extending MooseDocs

[vtnick]

Check these boxes if you have followed the posting rules.

• Q&A General is the most appropriate section for my question
• I have consulted the posting Guidelines on the Discussions front page
• I have searched the Discussions forum and my question has not been asked before
• I have searched the MOOSE website and the documentation does not answer my question
• I have formatted my post following the posting guidelines (screenshots as a last resort, triple back quotes around pasted text)

Question

What is the best/intended way to extend MooseDocs for a particular application?

In particular, to change the way latex renderer works. Latex tables/figures/code listings tend to be pretty specific to people/orgs but unlike with the html renderer there isnt a way to customize the latex output. For example, for my use case it makes more sense to use a lstlisting env rather than a verbatim. It would also be good to add a link to the listing source but the latex renderer doesnt do that. Things like figure/table placements could be handled through a style customization, but different env/packages are more difficult to do through that interface.

Right now I am attempting to fix these env and feature additions through python scripts and/or sed after the tex file is already created. But that approach seems fragile at best.

I considered forking MooseDocs into my own app, but that seems like it would make it more difficult to keep up with changes the MOOSE team makes.

[GiudGiud]

@cticenhour @aeslaughter what are your thoughts on this?

[aeslaughter]

It is possible to make an extension for your organization that could accomplish this, unless things have changed drastically in the past 5 years. The extension could live in your project. The system relies upon extensions to both tokenize and output. For this application you would only worry about the output portion. The custom extension would replace the what happens for a given token (e.g., Table) with whatever you would like to happen.

[vtnick]

well I was wondering how the moosedocs would know about my custom extension

[vtnick]

I assumed in the moosedocs.py I would just add a new path and provide the extension path similar to the others in the config MyCustom.path.newextension

[GiudGiud]

I think extensions are modules.
See load_extensions in load_config.py.
The list of extensions in config.yml gets passed to it, and as long as the module directory is in the PYTHONPATH it should get found

[aeslaughter]

• 'katex' extension is just for rendering the latex as html
• MooseDocs.extensions.katex in the config is the module, so you set your PYTHONPATH such that your module can load

[vtnick]

yeah I think we were just talking about katex as an example but that probably made the thread confusing.

I was able to add my own version of alert and have moosedocs find it. The only issue is I can't find the config that prevents the existing alert from being loaded...I have to rename my version of alert to something else.

I tried using the disable_defaults flag and then not loading MooseDocs.extensions.alert but the config tells me its required. If I load it but mark in active: False it complains when it loads my extension because the commands are the same.