# ANN: Documenter 1.0
**URL:** https://discourse.julialang.org/t/ann-documenter-1-0/103888
**Category:** Package Announcements
**Tags:** package, announcement, documenter
**Created:** [September 15, 2023, 11:10am UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888 "2023-09-15T11:10:46Z")
**Posts on this page:** 14
**Page:** 1
### Author:  [@mortenpi](https://discourse.julialang.org/u/mortenpi)
#### Post date: [September 15, 2023, 11:10am UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/1 "2023-09-15T11:10:46Z")
I am very pleased to announce the release of [Documenter](https://github.com/JuliaDocs/Documenter.jl) 1.0. It finally unleashes a bunch of great improvements and excellent contributions that have been “locked up” on master for the past year or so.
I am slightly less pleased to announce that, true to its nature as a major version change, the release does contain a few non-trivial breaking changes that will likely affect your documentation builds, and you will probably need to update your `make.jl` files. Please see the [release notes](https://documenter.juliadocs.org/v1.0.0/release-notes/) for details and instructions on how to upgrade.
I do want to thank everyone for their patience, which allowed us to get a big set of breaking changes all bunched up into a single release, reducing the disruption and breaking-release-churn in the ecosystem. I do hope that we will stay on 1.x for a while now, and will be able to have much more frequent non-breaking releases.
For most docs it should be safe to set Documenter compat to `Documenter = "1"` in `docs/Project.toml`. [Although you may want to double-check what SemVer guarantees mean in the context of Documenter, especially if you do non-trivial stuff in your `docs/make.jl`.](https://documenter.juliadocs.org/v1/lib/semver/)
As always, if you encounter any issues or errors, please don’t hesitate to open issues on [the Documenter issue tracker](https://github.com/JuliaDocs/Documenter.jl/issues).
Happy documenting! ✍
## Release highlights
First, I want to thank everyone who has contributed to Documenter, via PRs, issues, feedback, and helped us to get to this release! Here I just want to highlight a few of the [many-many changes and improvements that have happened over the past year](https://documenter.juliadocs.org/v1.0.0/release-notes/):
## New search interface
For the past several months, as part of his Summer of Code project, @Hetarth02 worked on improving the UI and UX of Documenter’s search, and Documenter now ships with a much more polished UI:
Under the hood, he also changed the JS search engine to [MiniSearch](https://lucaong.github.io/minisearch/), which is more actively maintained compared to the previously used lunr.js. You can also read [Hetarth’s GSoC submission](https://hetarth02.hashnode.dev/google-summer-of-code-2023-julia) for more details on this work.
## Link to repository
Tiny, but much-asked feature: Documenter now includes a link to the landing page of your package repository. Tangentially related to this is that Documenter is now much smarter and more consistent about handling the different remote links (page edit and Julia source links; this will also fix the source links of standard library functions in the Julia manual).
## PDF improvements
@odow contributed heaps of great fixes and improvements to the PDF/LaTeX backend, such as improved admonition, table, and code block styling and handling, which should come to your Julia Manual PDF soon.
## Strict by default
Documenter has quite a few checks to make sure that the generated documentation is not broken in some way. However, those only break builds if you set `strict = true`. When people don’t explicitly do that, they generally miss the warnings on documentation CI, and end up shipping half-broken documentation sites.
To encourage people to fix the issues as they come up, Documenter now runs in the `strict = true` mode by default (although that keyword has been removed; but you can still explicitly opt out from some or all checks with the new `warnonly` keyword).
Note that several new checks that have also been added, which may cause previously warning/error-free builds to error now.
## Catch large HTML pages
One _silent_ issue that quite a few documentation sites have is that their generated content (e.g. figures and other at-example block outputs) is leading to HTML pages that can be tens or even hundreds of megabytes, which in turn leads to a bad experience for the reader who opens it in the browser.
To nudge the authors to address this, Documenter will now by default complain if the generated examples pages are too big (the behavior can be controlled with the `size_threshold*` options). When it comes to generated images, like plots, Documenter will now write them into separate files, automatically helping reduce the size of the HTML files.
---
### Author:  [@tim.holy](https://discourse.julialang.org/u/tim.holy)
#### Post date: [September 15, 2023, 12:33pm UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/2 "2023-09-15T12:33:59Z")
This looks amazing, can’t wait to try it out! Thanks to the maintainers and the many who contributed.
---
### Author:  [@DanielVandH](https://discourse.julialang.org/u/DanielVandH)
#### Post date: [September 15, 2023, 12:53pm UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/3 "2023-09-15T12:53:32Z")
Amazing work! Great job. Especially like the new search - good job @Hetarth02 🙂
---
### Author:  [@cgarling](https://discourse.julialang.org/u/cgarling)
#### Post date: [September 15, 2023, 6:40pm UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/5 "2023-09-15T18:40:46Z")
Noticed this today and have been updating a few of my packages. Hasn’t been too bad so far; although I encountered several of the breaking changes, the provided changelog has been helpful in transitioning. Quite a few nice features to justify the update. Thanks! 🙂
---
### Author:  [@goerz](https://discourse.julialang.org/u/goerz)
#### Post date: [September 16, 2023, 6:08am UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/6 "2023-09-16T06:08:47Z")
For anyone who is using the [DocumenterCitations plugin](https://github.com/JuliaDocs/DocumenterCitations.jl) to add bibliographic references to their documentation: We also just released DocumenterCitations 1.2.0 to be compatible with Documenter 1.0.
A notable breaking change in Documenter 1.0 that affects any users of DocumenterCitations is that plugin objects now have to be passed to `makedocs` via a `plugins` keyword argument. For the old Documenter 0.27 / DocumenterCitations 1.1 your `docs/make.jl` file would have looked like this:
```julia
using DocumenterCitations
bib = CitationBibliography(
joinpath(@ __DIR__ , "src", "refs.bib");
style=:numeric
)
makedocs(bib, ...) # positional argument
```
With the new Documenter 1.0 / DocumenterCitations 1.2 you will have to change this to
```julia
makedocs(; plugins=[bib], ...)
```
Apart from compatibility with Documenter 1.0, changes since the [original announcement](https://discourse.julialang.org/t/ann-documentercitations-v1-0-0/101562) include a significantly improved [`:alpha` citation style](https://juliadocs.org/DocumenterCitations.jl/v1.2/gallery/#alphabetic_style) that avoids duplicate labels and [better support for preprint servers](https://juliadocs.org/DocumenterCitations.jl/v1.2/syntax/#Preprint-support) like arXiv. See [`NEWS.md`](https://github.com/JuliaDocs/DocumenterCitations.jl/blob/master/NEWS.md) for more details.
---
### Author:  [@jeremiedb](https://discourse.julialang.org/u/jeremiedb)
#### Post date: [September 28, 2023, 10:47pm UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/7 "2023-09-28T22:47:42Z")
Cograts on the v1 milestone!
Regarding `warnonly`, I resorted to using it in order to have the CI continue to work for my package. This was due to `docstring not included in the manual`. Is there a recommended practice for situation where on one hand I want to include docstring to internal functions (in order to have the source code documented), but not necessarily include them in the generatd user facing manual?
---
### Author:  [@wsshin](https://discourse.julialang.org/u/wsshin)
#### Post date: [September 29, 2023, 2:37pm UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/8 "2023-09-29T14:37:09Z")
I didn’t notice this in the documentations generated by the previous versions of Documenter, but maybe I was just ignorant: what is the upward arrowhead at the top-right corner, indicated by the red circle in the screenshot below?
Clicking it turns it to a downward arrowhead, but nothing happens.
---
### Author:  [@DanielVandH](https://discourse.julialang.org/u/DanielVandH)
#### Post date: [September 29, 2023, 2:46pm UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/9 "2023-09-29T14:46:00Z")
That collapses the docstrings - try it on this page [Public API · Documenter.jl](https://documenter.juliadocs.org/stable/lib/public/) (hovering over the arrow also shows this).
---
### Author:  [@franckgaga](https://discourse.julialang.org/u/franckgaga)
#### Post date: [September 30, 2023, 12:54am UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/10 "2023-09-30T00:54:57Z")
I love the the new version of Documenter. It’s really helpful for the development of my package. Keep up the good work ! 🙂
Francis
---
### Author:  [@gdalle](https://discourse.julialang.org/u/gdalle)
#### Post date: [September 30, 2023, 7:22am UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/11 "2023-09-30T07:22:27Z")
Gotta love how a bold breaking change (strict by default) is forcing the entire ecosystem to get their mess together and document stuff.
This is a non-negligible contribution to making _all_ of Julia more reliable. Thank you!
---
### Author:  [@mortenpi](https://discourse.julialang.org/u/mortenpi)
#### Post date: [October 6, 2023, 3:54am UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/12 "2023-10-06T03:54:09Z")
> [@jeremiedb](#):
>
> Is there a recommended practice for situation where on one hand I want to include docstring to internal functions (in order to have the source code documented), but not necessarily include them in the generatd user facing manual?
I’d say the current practice is to have an “internals” page where you include those docstrings. You can also hide that from the navigation menu with `Documenter.hide` if you want. That’s how Documenter itself does it, e.g. [Anchors · Documenter.jl](https://documenter.juliadocs.org/stable/lib/internals/anchors/)
---
### Author:  [@EssamWisam](https://discourse.julialang.org/u/EssamWisam)
#### Post date: [October 11, 2023, 2:23am UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/13 "2023-10-11T02:23:54Z")
Fantastic! Can’t wait for the release where syntax highlighting will be finally improved.
---
### Author:  [@Hetarth02](https://discourse.julialang.org/u/Hetarth02)
#### Post date: [October 14, 2023, 2:56am UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/14 "2023-10-14T02:56:57Z")
Thank you, glad you liked the new search. I hope to contribute more.
---
### Author:  [@heliosdrm](https://discourse.julialang.org/u/heliosdrm)
#### Post date: [March 24, 2024, 6:36pm UTC](https://discourse.julialang.org/t/ann-documenter-1-0/103888/15 "2024-03-24T18:36:33Z")
> [@mortenpi](#):
>
> To nudge the authors to address this, Documenter will now by default complain if the generated examples pages are too big (the behavior can be controlled with the `size_threshold*` options).
May those options (e.g. setting a custom threshold) be used when calling `makedocs`? I found a reference to `size_threshold` in the docs of `Documenter.HTMLWriter`, but I don’t know how to use it. I’m just using `makedocs` as explained in the guide of Documenter, and it seems that `size_threshold` is not a valid keyword for that function.