Customizing ExDoc templates

[tmbb]

Is it possible to customize the HTML templates without forking ExDoc? Or at least inject some CSS and Javascript?

[josevalim]

Not right now but we would gladly consider a pull request that supports such. Maybe we could have html_head key in the mix.exs which we simply inject in templates.

[tmbb]

I think we should add the following options:

• html_extra_head - text to include after the head (useful for CSS and maybe Javascript)
• html_extra_footer - text to include after the footer (useful for Javascript)
• extra_files - something like this:

%{
  # Static files (copy the file literally)
  "my-custom-script.js": {:path, "/priv/myscript.js"},
  "my-stylesheet.css": {:path, "priv/mystyle.css"},
  # Dynamic files (generated at compile time, for example:
  "my-dynamic.css": {:dynamic, My.Template.Generator.function}
}

I have real use cases at least for the :dynamic part.

What do you think?

[josevalim]

@tmbb then maybe it is better to allow you to hook into each HTML generated. We give you the whole HTML and you can do whatever you want with it. So custom_html: &add_extra/2 and for each generate HTML the function receives the filename (such as "search") and the whole body and it must return the body.

[tmbb]

That solves the first two points, not the third (it doesn't allow me to add my own Javascript and CSS files). And it would require manipulating an HTML document, which is not ideal. But if you think that's the best option, then ok. It's certainly the most flexible, short of overwriting the templates with custom ones supplied by the user (which might even be better).

For the second point, could you add a after_docs: &after_docs/1 function that takes the path of the output directory and makes whatever it wants? That would allow me to add the extra CSS and Javascript files with not problem.

[josevalim]

@tmbb today we already have a mechanism for including extra assets in the docs. Check the "assets" configuration.

[josevalim]

We cannot allow templates to be overridden because that would require us to have a explicit contract on the data that is sent from ExDoc to the templates and that will make it harder for us to improve ExDoc in the future.

To sum up, I think we have two options:

1. :before_closing_head_tag and :before_closing_body_tag can be set with HTML contents that will be injected in templates as is
2. custom_html: &some_fun/2 that gives you the whole file

1 is easier to use, 2 is more general.

[tmbb]

Check the "assets" configuration.

Sorry, I looked for it in the README and missed the mix help docs task. I've seen it now. It supports static assets which are in fact good enough for what I need.

[tmbb]

Regarding the two options, I'm not sure... I'm tempted to go with option 1 because messing with an already generated HTML file is messy. But I worry than in a few months I might regret that choice and want something like option 2.

I think we should go with option number 1, and if someone asks for option number 2 that can always be implemented later. Given that you can choose to use a custom markdown implementation, I think many customizations can be made there.

What do you think? Option 2 is compatible with option 1, so we can always add it later.

[josevalim]

As you please. You are the "first customer", so you get to build the menu. ;)

[tmbb]

How would you like to pass these options? Like this?

def project do
  [app: :my_app,
   version: "0.1.0-dev",
   deps: deps(),
   # Docs
   name: "MyApp",
   source_url: "https://github.com/USER/PROJECT",
   homepage_url: "http://YOUR_PROJECT_HOMEPAGE",
   docs: [main: "MyApp", # The main page in the docs
          logo: "path/to/logo.png",
          extras: ["README.md"]
          before_closing_head_tag: "...",
          before_closing_body_tag: "..."]]
end

And also related: Why is the markdown passed like this:

config :ex_doc, :markdown_processor, ExDoc.Markdown.Hoedown

instead of being passed from the project.docs keyword list? Can't we have everything in one place?

[josevalim]

Like that sounds good. And we can pass the markdown processor via mix.exs as well, good call.