Skip to content

Users can now add custom HTML before the closing head tag and the closing body tag #764

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 2, 2017
Merged

Users can now add custom HTML before the closing head tag and the closing body tag #764

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dcad862
Markdown modules are now 100% responsible for code
tmbb Aug 2, 2017
34ae4f2
Added options to customize templates
tmbb Aug 2, 2017
1559a65
Added new options to `mix help docs`
tmbb Aug 2, 2017
51662e6
Merge branch 'master' of https://github.com/elixir-lang/ex_doc
tmbb Aug 2, 2017
feb2c78
before_closing_*_tags have their own test now
tmbb Aug 2, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions lib/ex_doc.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ defmodule ExDoc do

defstruct [
assets: nil,
before_closing_head_tag: "",
before_closing_body_tag: "",
canonical: nil,
debug: false,
deps: [],
Expand All @@ -51,6 +53,8 @@ defmodule ExDoc do

@type t :: %__MODULE__{
assets: nil | String.t,
before_closing_head_tag: String.t,
before_closing_body_tag: String.t,
canonical: nil | String.t,
debug: boolean(),
deps: [{ebin_path :: String.t, doc_url :: String.t}],
Expand Down
1 change: 1 addition & 0 deletions lib/ex_doc/formatter/html/templates/footer_template.eex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,5 +16,6 @@
</section>
</div>
<script src="<%= asset_rev config.output, "dist/app*.js" %>"></script>
<%= config.before_closing_body_tag %>
</body>
</html>
1 change: 1 addition & 0 deletions lib/ex_doc/formatter/html/templates/head_template.eex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
<link rel="canonical" href="<%= config.canonical %>" />
<% end %>
<script src="<%= asset_rev config.output, "dist/sidebar_items*.js" %>"></script>
<%= config.before_closing_head_tag %>
</head>
<body data-type="<%= sidebar_type(page.type) %>">
<script>try { if(localStorage.getItem('night-mode')) document.body.className += ' night-mode'; } catch (e) { }</script>
8 changes: 8 additions & 0 deletions lib/mix/tasks/docs.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,14 @@ defmodule Mix.Tasks.Docs do
directory in the output path. Its entries may be referenced in your docs
under "assets/ASSET.EXTENSION"; defaults to no assets directory.

* `:before_closing_body_tag` - Literal HTML to be included just before the closing body tag (`</body>`)
Useful to inject custom assets, such as Javascript.
Only works with the HTML formatter.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tmbb @josevalim Why? This should also work with EPUB documents, at the end, an EPUB file is just a bunch of .xhtml files.

Copy link
Contributor Author

@tmbb tmbb Aug 2, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because I've only added this functionality to the HTML templates :) If you want it, I can add it to the EPUB ones.


* `:before_closing_head_tag` - Literal HTML to be included just before the closing head tag (`</head>`);
Useful to inject custom assets, such as CSS.
Only works with the HTML formatter.

* `:canonical` - String that defines the preferred URL with the rel="canonical"
element; defaults to no canonical path.

Expand Down
24 changes: 23 additions & 1 deletion test/ex_doc/formatter/html_test.exs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@ defmodule ExDoc.Formatter.HTMLTest do
File.read!(file)
end

@before_closing_head_tag "UNIQUE:<dont-escape>&copy;BEFORE-CLOSING-HEAD-TAG</dont-escape>"
@before_closing_body_tag "UNIQUE:<dont-escape>&copyBEFORE-CLOSING-BODY-TAG</dont-escape>"

defp doc_config do
[project: "Elixir",
version: "1.0.1",
Expand All @@ -29,7 +32,9 @@ defmodule ExDoc.Formatter.HTMLTest do
source_root: beam_dir(),
source_beam: beam_dir(),
logo: "test/fixtures/elixir.png",
extras: ["test/fixtures/README.md"]]
extras: ["test/fixtures/README.md"],
before_closing_head_tag: @before_closing_head_tag,
before_closing_body_tag: @before_closing_body_tag]
end

defp doc_config(config) do
Expand Down Expand Up @@ -204,6 +209,23 @@ defmodule ExDoc.Formatter.HTMLTest do
assert content =~ ~r{<a href="TypesAndSpecs.Sub.html"><code(\sclass="inline")?>TypesAndSpecs.Sub</code></a>}
end

test "before_closing_*_tags are placed in the right place - api reference file" do
generate_docs(doc_config())

content = File.read!("#{output_dir()}/api-reference.html")
assert content =~ ~r[#{@before_closing_head_tag}\s*</head>]
assert content =~ ~r[#{@before_closing_body_tag}\s*</body>]
end

test "before_closing_*_tags are placed in the right place - generated pages" do
config = doc_config([main: "readme"])
generate_docs(config)

content = File.read!("#{output_dir()}/readme.html")
assert content =~ ~r[#{@before_closing_head_tag}\s*</head>]
assert content =~ ~r[#{@before_closing_body_tag}\s*</body>]
end

test "run generates pages with custom names" do
generate_docs(doc_config(extras: ["test/fixtures/README.md": [filename: "GETTING-STARTED"]]))
refute File.regular?("#{output_dir()}/readme.html")
Expand Down