# Deploying documentation with Documenter (automatically with each new push to the repo)

**URL:** <https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615>\
**Category:** General Usage\
**Tags:** package, documentation\
**Created:** [March 20, 2021, 5:37pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615 "2021-03-20T17:37:41Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![Gus\_Hart](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gus_hart/32/6987_2.png) [@Gus\_Hart](https://discourse.julialang.org/u/Gus_Hart)\
**Post date:** [March 20, 2021, 5:37pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/1 "2021-03-20T17:37:41Z")

</div>

I made a small package as a way of “practicing” all of the good software practices (CI, unit tests, coverage testing, etc). Here it is: [GitHub - glwhart/MinkowskiReduction.jl: Lattice reduction in three dimensions](https://github.com/glwhart/MinkowskiReduction.jl)

I used a template and PkgTemplate. I finally got coverage testing and travis and all that working. When I make a change and push to the repo, all the tests run, the badges are updated, etc.

But I can’t get the documentation to show up on github. (You’ll notice that the docs badge is a broken link…[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://glwhart.github.io/MinkowskiReduction.jl/dev))

In fact, the documentation is not being deployed to `gh-pages` branch on the package’s repo. When `make.jl` runs, the documentation is created—I can see it a `build` directory inside `docs`. But the contents don’t automatically get pushed to github. I can’t figure out why. I believe I followed all the directions given in the Documenter.jl docs (like adding keys, etc.), but I’m still stuck.

When I run `julia make.jl` in the docs. It looks like this:

```julia
➜ dev/MinkowskiReduction/docs git:(main) ✗ julia make.jl 
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
┌ Warning: Documenter could not auto-detect the building environment Skipping deployment.
└ @ Documenter ~/.julia/packages/Documenter/bFHi4/src/deployconfig.jl:75

```

Not sure that Warning is relevant…but ‘skipping deployment’ sounds like my problem. Not sure why the building environment is not known. To me it’s obviously the `docs/build` folder…

Any ideas what I failed to do in my setup? Or what maybe I did wrong?

Is there some log file or something I should be looking at to debug this? Sorry for the newbie questions. I’m still figuring out all the package stuff.

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [March 20, 2021, 6:10pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/2 "2021-03-20T18:10:14Z")

</div>

I have struggled a bit with that, and annotated my workflow here: [Publish Docs · JuliaNotes.jl](https://m3g.github.io/JuliaNotes.jl/stable/publish_docs/)

---

<div class="post-metadata">

**Author:** ![Gus\_Hart](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gus_hart/32/6987_2.png) [@Gus\_Hart](https://discourse.julialang.org/u/Gus_Hart)\
**Post date:** [March 22, 2021, 2:33pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/3 "2021-03-22T14:33:03Z")

</div>

Thank you @lmiq. I looked through your notes carefully and I did learn a couple of things.

However, I’m still not getting my docs to show up at [Home · MinkowskiReduction.jl](https://glwhart.github.io/MinkowskiReduction.jl/)

I have two questions for the community at large.

1. If everything is working, should I see html files in my `gh-pages` branch on my github repo?
2. If I run `julia make.jl` on my local copy of the repo (rather than having travis-ci do it, or github actions) should it still work? Should it deploy my docs to github?

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [March 22, 2021, 2:49pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/4 "2021-03-22T14:49:54Z")

</div>

> [@Gus\_Hart](#):
>
> If everything is working, should I see html files in my `gh-pages` branch on my github repo?

Yes, and that seems to be ok in your repo.

> [@Gus\_Hart](#):
>
> If I run `julia make.jl` on my local copy of the repo (rather than having travis-ci do it, or github actions) should it still work? Should it deploy my docs to github?

That will create a local copy of the page. You can see and edit it locally. I use a simple script that launches a python-based local server (`http.server`) for that:

```julia
# file: webserver.sh
previous=`ps aux | grep python3 |grep http.server| awk '{print $2}'`
if [[$previous > ""]];then 
  kill -9 $previous
fi
python3 -m http.server --bind localhost

```

If you run `webserver.sh` from the `build` directory created with `make.jl` you will be able to see your page at `http://127.0.0.1:8000/`.

But, answering your question, that does not publish your docs.

Finally, I can’t see anything wrong with your docs. Did you do, in github:

`Settings -> GitHub Pages -> choose gh-pages (/root)`

I am not sure if that is not done automatically, but I always did that.

---

<div class="post-metadata">

**Author:** ![Gus\_Hart](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/gus_hart/32/6987_2.png) [@Gus\_Hart](https://discourse.julialang.org/u/Gus_Hart)\
**Post date:** [March 22, 2021, 5:32pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/5 "2021-03-22T17:32:48Z")

</div>

Oh! Almost there! I hadn’t changed the settings in the repo:  
`Settings -> GitHub Pages -> choose gh-pages (/root)`

Now with that change, the documentation is visible at:  
[https://glwhart.github.io/MinkowskiReduction.jl/](https://glwhart.github.io/MinkowskiReduction.jl/)

but my badges created by the `PkgTemplate` package point to `dev` and `stable` branches so those links are still broken…(I guess I’ll live without different branches of the docs for now).

But I’m really excited to have the documentation showing up finally. Thank you!

---

<div class="post-metadata">

**Author:** ![weymouth](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/weymouth/32/15839_2.png) [@weymouth](https://discourse.julialang.org/u/weymouth)\
**Post date:** [July 16, 2021, 4:30pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/6 "2021-07-16T16:30:45Z")

</div>

I can’t get the html pages to build on my project [WaterLily.jl](https://github.com/weymouth/WaterLily.jl) and I’m general confused about the `gh-pages` branch. Why is this needed and what should be different on this branch compared to `master`? Every time I make a change on `master`, will I have to merge that change into `gh-pages` in order to refresh the documents (once I actually get them working)?

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [July 16, 2021, 4:36pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/7 "2021-07-16T16:36:24Z")

</div>

The `gh-pages` banch should not contain the code contained in the main branch. It is started as an empty branch (either manually, or automatically when the documentation is deployed for the first time), and when the documentation is deployed, the built docs are stored there. For example:

Main branch: [https://github.com/m3g/SPGBox.jl](https://github.com/m3g/SPGBox.jl)

gh-pages branch: [GitHub - m3g/SPGBox.jl at gh-pages](https://github.com/m3g/SPGBox.jl/tree/gh-pages)

---

<div class="post-metadata">

**Author:** ![weymouth](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/weymouth/32/15839_2.png) [@weymouth](https://discourse.julialang.org/u/weymouth)\
**Post date:** [July 16, 2021, 6:09pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/8 "2021-07-16T18:09:27Z")

</div>

Progress!

- Github actions automatically made `gh-pages`!
- I see the index.html file in the `dev` folder
- [The website](https://weymouth.github.io/WaterLily.jl/) is still giving a 404.

How does github know which index.html to use? I noticed your example has 20 folders in it…

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [July 16, 2021, 6:11pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/9 "2021-07-16T18:11:54Z")

</div>

Now probably you have to deploy again the stable version, with this: [Publish Docs · JuliaNotes.jl](https://m3g.github.io/JuliaNotes.jl/stable/publish_docs/#Deployment-of-the-docs-of-a-previous-version)

(bottom of the page)

But next time you create a tag, probably everything will work.

ps: The site will be called `https://weymouth.github.io/WaterLily.jl/stable`

and this: [WaterLily · WaterLily.jl](https://weymouth.github.io/WaterLily.jl/dev)

is working already.

---

<div class="post-metadata">

**Author:** ![weymouth](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/weymouth/32/15839_2.png) [@weymouth](https://discourse.julialang.org/u/weymouth)\
**Post date:** [July 16, 2021, 10:36pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/10 "2021-07-16T22:36:20Z")

</div>

Oh, cool. That’ll work!

---

<div class="post-metadata">

**Author:** ![AntoineRestivo](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/antoinerestivo/32/36509_2.png) [@AntoineRestivo](https://discourse.julialang.org/u/AntoineRestivo)\
**Post date:** [May 23, 2022, 1:25pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/11 "2022-05-23T13:25:40Z")

</div>

Hey everyone! I first apologise to revive this topic but I’ve been following @Imiq guide [Publish Docs · JuliaNotes.jl](https://m3g.github.io/JuliaNotes.jl/stable/publish_docs/) for the keys generation etc but still, my (manually created) gh-pages branch remains empty after the deployment action… Here is the package [GitHub - AntoineRestivo/BosonSampling.jl: Boson sampling tools for Julia](https://github.com/AntoineRestivo/BosonSampling.jl). I was wondering wether I need to put the value of the (public) key somewhere in the workflow files or not.

Thanks in advance!

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [May 23, 2022, 3:04pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/12 "2022-05-23T15:04:55Z")

</div>

My understanding of that is only empirical, but creating an empty branch is different from creating a branch with nothing in it. I can only recommend deleting that branch and starting over, creating the empty branch from the GitHub site.

---

<div class="post-metadata">

**Author:** ![AntoineRestivo](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/antoinerestivo/32/36509_2.png) [@AntoineRestivo](https://discourse.julialang.org/u/AntoineRestivo)\
**Post date:** [May 23, 2022, 7:13pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/13 "2022-05-23T19:13:19Z")

</div>

Thanks for your prompt reply! Even by creating gh-pages properly as an orphan branch, our documentation still comes from the readme file only.

---

<div class="post-metadata">

**Author:** ![AntoineRestivo](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/antoinerestivo/32/36509_2.png) [@AntoineRestivo](https://discourse.julialang.org/u/AntoineRestivo)\
**Post date:** [May 26, 2022, 7:15am UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/14 "2022-05-26T07:15:51Z")

</div>

For completeness, my problem is resolved thanks to a ci.yml file. Your previous answers were really helpful!

---

<div class="post-metadata">

**Author:** ![Shayan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/shayan/32/33025_2.png) [@Shayan](https://discourse.julialang.org/u/Shayan)\
**Post date:** [March 23, 2023, 7:29pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/15 "2023-03-23T19:29:50Z")

</div>

Hi, I followed the instructions from this “[Publish Docs · JuliaNotes.jl](https://m3g.github.io/JuliaNotes.jl/stable/publish_docs/#Use-DocumenterTools-to-generate-the-keys)” topic, but I didn’t manage to deploy GitHub Pages. The repository is [GitHub - shayandavoodii/MFF](https://github.com/shayandavoodii/MFF) and the error of CI workflow is as follows:

> **CI error**
>
> The error is available here: [removed · shayandavoodii/MFF@ed7694d · GitHub](https://github.com/shayandavoodii/MFF/actions/runs/4504303464/jobs/7928609620)
> 
> ```julia
> Run julia --project=docs -e '
> Installing known registries into `~/.julia`
> Updating registry at `~/.julia/registries/General.toml`
> Resolving package versions...
> ERROR: expected package `MFF [99a43ef4]` to be registered
> Stacktrace:
> [1] pkgerror(msg::String)
> @ Pkg.Types /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/Types.jl:67
> [2] check_registered
> @ /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/Operations.jl:1190 [inlined]
> [3] targeted_resolve(env::Pkg.Types.EnvCache, registries::Vector{Pkg.Registry.RegistryInstance}, pkgs::Vector{Pkg.Types.PackageSpec}, preserve::Pkg.Types.PreserveLevel, julia_version::VersionNumber)
> @ Pkg.Operations /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/Operations.jl:1252
> [4] tiered_resolve(env::Pkg.Types.EnvCache, registries::Vector{Pkg.Registry.RegistryInstance}, pkgs::Vector{Pkg.Types.PackageSpec}, julia_version::VersionNumber)
> @ Pkg.Operations /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/Operations.jl:1225
> [5] _resolve(io::Base.PipeEndpoint, env::Pkg.Types.EnvCache, registries::Vector{Pkg.Registry.RegistryInstance}, pkgs::Vector{Pkg.Types.PackageSpec}, preserve::Pkg.Types.PreserveLevel, julia_version::VersionNumber)
> @ Pkg.Operations /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/Operations.jl:1260
> [6] add(ctx::Pkg.Types.Context, pkgs::Vector{Pkg.Types.PackageSpec}, new_git::Set{Base.UUID}; preserve::Pkg.Types.PreserveLevel, platform::Base.BinaryPlatforms.Platform)
> @ Pkg.Operations /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/Operations.jl:1276
> [7] add(ctx::Pkg.Types.Context, pkgs::Vector{Pkg.Types.PackageSpec}; preserve::Pkg.Types.PreserveLevel, platform::Base.BinaryPlatforms.Platform, kwargs::Base.Pairs{Symbol, Base.PipeEndpoint, Tuple{Symbol}, NamedTuple{(:io,), Tuple{Base.PipeEndpoint}}})
> @ Pkg.API /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:275
> [8] add(pkgs::Vector{Pkg.Types.PackageSpec}; io::Base.PipeEndpoint, kwargs::Base.Pairs{Symbol, Union{}, Tuple{}, NamedTuple{(), Tuple{}}})
> @ Pkg.API /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:156
> [9] add(pkgs::Vector{Pkg.Types.PackageSpec})
> @ Pkg.API /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:145
> [10] #add#27
> @ /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:144 [inlined]
> [11] add
> @ /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:144 [inlined]
> [12] #add#26
> @ /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:143 [inlined]
> [13] add(pkg::String)
> @ Pkg.API /opt/hostedtoolcache/julia/1.8.5/x64/share/julia/stdlib/v1.8/Pkg/src/API.jl:143
> [14] top-level scope
> @ none:2
> Error: Process completed with exit code 1.
> 
> ```

I get “file not found” in [https://shayandavoodii.github.io/MFF/](https://shayandavoodii.github.io/MFF/).

Note that [MFF](https://github.com/shayandavoodii/MFF/) is not intended to be registered.

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [March 23, 2023, 7:35pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/16 "2023-03-23T19:35:11Z")

</div>

I think your gh-pages branch is not an originally empty branch to be populated automatically by the CI run. That may be a problem.

---

<div class="post-metadata">

**Author:** ![Shayan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/shayan/32/33025_2.png) [@Shayan](https://discourse.julialang.org/u/Shayan)\
**Post date:** [March 23, 2023, 7:37pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/17 "2023-03-23T19:37:27Z")

</div>

So, should I remove the branch, and initialize a new empty branch and paste the contents in it?

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [March 23, 2023, 7:38pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/18 "2023-03-23T19:38:52Z")

</div>

As far as I understand, yes, you need to remove the branch and create an empty one. But you don’t need to do anything else, the content will be created automatically by the CI script once you tag a new version. (this part: [Publish Docs · JuliaNotes.jl](https://m3g.github.io/JuliaNotes.jl/stable/publish_docs/#Create-an-empty-gh-pages-branch-and-choose-it-to-deploy-the-page))

---

<div class="post-metadata">

**Author:** ![Shayan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/shayan/32/33025_2.png) [@Shayan](https://discourse.julialang.org/u/Shayan)\
**Post date:** [March 23, 2023, 7:41pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/19 "2023-03-23T19:41:01Z")

</div>

> [@lmiq](#):
>
> the content will be created automatically by the CI script

Do you mean CI workflow reads the content of the `master` branch and automatically handles creating `gh-branch` and deployment?

---

<div class="post-metadata">

**Author:** ![Shayan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/shayan/32/33025_2.png) [@Shayan](https://discourse.julialang.org/u/Shayan)\
**Post date:** [March 23, 2023, 7:51pm UTC](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615/20 "2023-03-23T19:51:22Z")

</div>

I removed the `gh-pages` branch and followed the [commands that you referred to](https://m3g.github.io/JuliaNotes.jl/stable/publish_docs/#Create-an-empty-gh-pages-branch-and-choose-it-to-deploy-the-page). So, the new fresh `gh-pages` got created. Afterward, I published a new release, but the error remained as before.

> [@Shayan](#):
>
> the error of CI workflow is as follows: …

Also, the `gh-pages` branch is empty still.

[Next page](https://discourse.julialang.org/t/deploying-documentation-with-documenter-automatically-with-each-new-push-to-the-repo/57615.md?page=2)