JuliaDocs / Documenter.jl

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

allow plugins to pass asset additions #1612

Open LazyScholar opened 3 years ago

LazyScholar commented 3 years ago

It would be nice to allow plugins like DocumenterCitations.jl to pass css-style additions to the Documenter.jl html-writer assets.

This would allow to add own plugin specific css styles to enhance readability of elements which are added to the HTML documentation by a plugin (without starting to clutter the Documenter.jl default style).

This might also allow the creation of plugins with advanced .js capabilities (a option to limit additions of assets like .css or .js to the scope of the plugin (instead of each page) might be needed here).

Currently this could only be done by raw html insertion into the markdown (by the user or the plugin), by element wise css modification by the plugin or by manually adding a css asset .


Probably related/conflicting: #615 #982 #1433


Examples which could be improved by small plugin css additions:

DocumenterCitations.jl

```@raw html
<style>
dl {
display: grid;
grid-template-columns: max-content auto;
}
dt {
grid-column-start: 1;
}
dd {
grid-column-start: 2;
margin-bottom: 0.75em;
}
</style>
pure  |  with css addition
:-------------------------:|:-------------------------:
![bib1](https://user-images.githubusercontent.com/75576197/123248614-695aed80-d4e8-11eb-85bc-592291b7e481.png)  |   ![bib2](https://user-images.githubusercontent.com/75576197/123248618-69f38400-d4e8-11eb-8e25-e4e75170caa8.png)

[`DocStringExtensions.jl`](https://github.com/JuliaDocs/DocStringExtensions.jl)
<style>
#horlist ul {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(25ch, 1fr));
grid-gap: 4px;
list-style: none;
}
</style>
<div id="horlist">
NURBStoolbox
</div>
pure  |  with css addition
:-------------------------:|:-------------------------:
![exp1](https://user-images.githubusercontent.com/75576197/123249077-e6866280-d4e8-11eb-9986-d6e55dae3295.png) | ![exp2](https://user-images.githubusercontent.com/75576197/123249078-e71ef900-d4e8-11eb-830b-64103cbd0d29.png)

[`DocStringExtensions.jl`](https://github.com/JuliaDocs/DocStringExtensions.jl)
<style>
#horfield li > p + p::before {
content: ": ";
}
#horfield li > p {
display: contents;
}
</style>
<div id="horfield">
NURBS
NURBS1D
NURBS2D
</div>

pure  |  with css addition
:-------------------------:|:-------------------------:
![field1](https://user-images.githubusercontent.com/75576197/123249259-103f8980-d4e9-11eb-8b23-43e78c82418f.png) | ![field2](https://user-images.githubusercontent.com/75576197/123249263-10d82000-d4e9-11eb-9c34-ff897ee38dbf.png)
mortenpi commented 3 years ago

If dropping in another CSS file would be sufficient, we could add some API where each plugin provides extra HTML assets.

Currently we loop over the .assets field of the HTML object to add user-defined assets: https://github.com/JuliaDocs/Documenter.jl/blob/dd7eebed2c0633b99954447e796194bd46cd1acb/src/Writers/HTMLWriter.jl#L886

In the same place we could loop over each plugin in ctx.documenter.plugins and ask if it also wants to add some extra assets.