Serving Docs from within an App

I thought it would be a good idea to serve my documentation for a client through a route in the application, I didn’t think it would be a good idea to just give them a folder full of html files and the epub file ex_doc generates is not styled nearly up to par in my opinion.

So I generated my documentation, created a resources "/", DocsController route, (painfully) manually converted each html file into an html.eex extension and moved the entire docs folder within templates. All really simple but I feel like there is a better way to do all of this and probably a few improvements I could make otherwise if anyone has any suggestions I appreciate it.

My controller looks like:

def index(conn, _params) do
  render(conn, "index.html")

def show(conn, %{"id" => id}) do
  render(conn, id)

Currently trying to get the styling and sidebar from /dist to correctly render.

1 Like

Why not let a dedicated http server like nginx serve the static HTML files?

I’ve this for development in my endpoint.ex:

  # Serve at "/doc" the static files from ex_doc.
  if Mix.env() == :dev do
    plug Plug.Static, at: "/docs", from: "doc", gzip: false

    plug Plug.Static, at: "/coverage", from: "cover", gzip: false

only issue is that it’s missing redirect from /docs => /docs/index.html


I’ve been trying to avoid using something like nginx for simplicity. What would the benefits be?

Significantly faster static file hosting, easier SSL updating, able to host multiple servers on the same port, few other things, you lose HTTP2 if that matters though. :slight_smile:


But if you’re not serving too many static files/getting a lot of requests for these docs than I think it probably won’t be worth it.

1 Like

Exactly. I don’t mess with nginx for little things. I do use it heavily when I use lots of subdomains or hosting lots of different applications in subpaths on a single server though. :slight_smile:


Definitely. I usually use nginx when I reuse a singular small-ish server for a number of purposes. F.ex. I’ve had 3 separate project’s reporting subsystems hosted on such a server, and then one day I figured I’ll just put 10+ Swagger / ex_doc documentation packages there because they are rarely used and have practially zero footprint.

For a quick solution, what @LostKobrakai suggested is the best course of action.

1 Like