# \[ANN\] Publish.jl
**URL:** https://discourse.julialang.org/t/ann-publish-jl/45500
**Category:** Package Announcements
**Created:** [August 25, 2020, 12:21pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500 "2020-08-25T12:21:14Z")
**Posts on this page:** 20
**Page:** 1
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [August 25, 2020, 12:21pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/1 "2020-08-25T12:21:14Z")
Hi all,
I’m pleased to announce the (_very early_) 0.1 release of [Publish.jl](https://github.com/MichaelHatherly/Publish.jl). An experimental package in the same ecosystem “space” as [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl). It’s purpose is to explore alternative design decisions (potentially major and breaking ones) to those that we’ve taken over the years with Documenter, with the hopes to eventually upstream/integrate them in some way with the rest of the ecosystem.
**What Publish.jl aims to provide?**
- Declarative configurations rather than build scripts.
- Fully compliant commonmark parsing (plus useful extensions).
- Cross-references across packages (awaiting a suitable syntax before finishing implementing).
- General enough to be used not just for “package documentation”, but any kind of writing.
- Full style and template customisation exposed to the user.
- PDF output without having to manage any kind of LaTex environment.
- Integrated project watching with LiveServer.jl.
- And anything else we want, [we’re greedy](https://julialang.org/blog/2012/02/why-we-created-julia/)…
**How far along is it?**
I’ve used it build it’s own package documentation in it’s entirety, so in that sense it’s already usable. Styling is still bare-bones with the built in templates, but those are easily replaceable by users and future improvements for the defaults are planned.
**How to try it?**
```julia
pkg> add Publish
julia> using Publish
julia> serve(Publish) # start server to serve Publish's docs.
```
The [package docs](https://michaelhatherly.github.io/Publish.jl/0.1.0/README.html) go into much more depth on what’s available at the moment.
**It’s broken?**
Please [open an issue](https://github.com/MichaelHatherly/Publish.jl/issues), it’s very likely there’ll be stuff that’s boken/not implemented currently.
---
### Author:  [@rdeits](https://discourse.julialang.org/u/rdeits)
#### Post date: [August 25, 2020, 2:16pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/2 "2020-08-25T14:16:32Z")
Very cool! I’m excited to try this out.
Is the layout supposed to be mobile-style on all displays? I checked out the sample docs on my desktop, and the layout looks like it thinks I’m using a phone or other small screen with all of the navigation contents hidden behind a hamburger menu:
Is that an intentional design choice or maybe just a `
### Author:  [@tamasgal](https://discourse.julialang.org/u/tamasgal)
#### Post date: [August 25, 2020, 2:36pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/3 "2020-08-25T14:36:40Z")
I just wanted to ask the same 😉
Otherwise, really nice, I like the user-oriented approach and the reactive way of working on the docs, very cool!
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [August 25, 2020, 2:37pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/4 "2020-08-25T14:37:23Z")
It’s intensional at the moment, in the sense that I’ve just not written the CSS yet to adjust the layout based on screen size 😃 it’s on the to-do list though.
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [August 25, 2020, 2:45pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/5 "2020-08-25T14:45:46Z")
> [@tamasgal](#):
>
> the reactive way of working on the docs, very cool
Yeah, it’s nice being able to get instant feedback. You can get the same effect with Documenter by importing LiveServer.jl yourself, though it feels like it should be a built in feature so that users will use that workflow by default.
It’s not mentioned early in the docs, but this also works with live reloading docstrings with Revise if you happen to have that loaded as well.
---
### Author:  [@singularitti](https://discourse.julialang.org/u/singularitti)
#### Post date: [August 25, 2020, 4:03pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/6 "2020-08-25T16:03:03Z")
Will it provide a theme that looks like Documenter.jl? Kinda like Documenter’s layout & it has been widely used. Also, does it provide a dark theme?
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [August 25, 2020, 4:23pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/7 "2020-08-25T16:23:44Z")
All those are on the roadmap. I’ll get to them at some point.
---
### Author:  [@Roger-luo](https://discourse.julialang.org/u/Roger-luo)
#### Post date: [August 25, 2020, 7:26pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/8 "2020-08-25T19:26:48Z")
I like the idea to use `Project.toml` and `toc.md` for the configuration. Just wondering if it’s better to have the `Documenter` folder structure, that lets all doc related files live inside `docs` folder and allow some documentation specific dependencies and configurations in `docs/Project.toml`, so that what’s inside `docs` becomes
```julia
docs/Project.toml
docs/toc.md
docs/src/
docs/assets
```
which looks more organized to me.
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [August 25, 2020, 7:58pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/9 "2020-08-25T19:58:17Z")
> [@Roger-luo](#):
>
> Just wondering if it’s better to have the `Documenter` folder structure, that lets all doc related files live inside `docs` folder and allow some documentation specific dependencies and configurations in `docs/Project.toml`
Right, the default structure that Publish accepts isn’t going to be suitable for all projects, hence why you can adjust the paths in your `Project.toml` such as:
```toml
[publish]
toc = "docs/toc.md"
[publish.html]
css = ["docs/assets/custom.css"]
```
To point your table-of-contents and custom CSS (or anything else you’re using) at files in your `docs/` directory. That’s one option and allows referencing content in your `src/` directory if you’re wanting to use the package source code for some literate programming.
The other option is to use a separate `docs/Project.toml`, which is fine. It’ll just not allow you to directly reference any files outside of the `docs/` directory tree. When you use `serve` or `deploy` to generate output, just point them at the configuration rather than the `Module` object, i.e.
```julia
julia> serve("docs/Project.toml")
```
This will currently **not** pick up docstring references from the package, which is an oversight on my part, but shouldn’t be too hard to fix for the next release so that you can specify which modules to check within your configuration.
---
### Author:  [@simeonschaub](https://discourse.julialang.org/u/simeonschaub)
#### Post date: [August 25, 2020, 8:57pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/10 "2020-08-25T20:57:23Z")
One situation, where putting the Project.toml under a `docs/` folder might be useful would be for doctest-specific dependencies. It doesn’t look like doctests are currently supported, but might be added eventually? Perhaps that could also be it’s own entry under `[publish]`, but in that case it probably wouldn’t be possible to just activate the project for debugging.
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [August 26, 2020, 8:11am UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/11 "2020-08-26T08:11:39Z")
> [@simeonschaub](#):
>
> One situation, where putting the Project.toml under a `docs/` folder might be useful would be for doctest-specific dependencies. It doesn’t look like doctests are currently supported, but might be added eventually?
Yes, if you’re needing doctest only deps then a separate `docs/Project.toml` is the correct way to use Publish. Some form of doctesting will definitely be added at some point.
---
### Author:  [@holylorenzo](https://discourse.julialang.org/u/holylorenzo)
#### Post date: [August 26, 2020, 12:21pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/12 "2020-08-26T12:21:08Z")
This is exactly what I’ve been looking for for months now, so thank you for building it!
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [August 29, 2020, 8:11pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/13 "2020-08-29T20:11:59Z")
0.2 is now out. Theming is better exposed to users, so most of the stylistic elements of the output can be switched out for completely custom looking results.
Additionally the package has had some internal refactoring to use FileTrees.jl for the internal representation, which allows for lazy evaluation of files and parallel writing of output. Parallel writing doesn’t appear to have much benefit on small projects and so it isn’t enabled by default, but may help on very large ones.
---
### Author:  [@holylorenzo](https://discourse.julialang.org/u/holylorenzo)
#### Post date: [August 31, 2020, 10:40am UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/14 "2020-08-31T10:40:01Z")
I’ve used Publish.jl to host my first package documentation and it was a breeze!
[https://lorenzoh.github.io/DataLoaders.jl/dev](https://lorenzoh.github.io/DataLoaders.jl/dev)
---
### Author:  [@kristoffer.carlsson](https://discourse.julialang.org/u/kristoffer.carlsson)
#### Post date: [August 31, 2020, 11:03am UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/15 "2020-08-31T11:03:02Z")
Should it be “Built” instead of “Build” in the footer?
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [August 31, 2020, 8:29pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/16 "2020-08-31T20:29:40Z")
🤣 yeah that should be “built”, thanks.
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [August 31, 2020, 10:05pm UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/17 "2020-08-31T22:05:53Z")
The newly tagged 0.3 adds [evaluation of code blocks](https://michaelhatherly.github.io/Publish.jl/dev/docs/cells.html) as well as a few minor bug fixes and typos.
---
### Author:  [@kristoffer.carlsson](https://discourse.julialang.org/u/kristoffer.carlsson)
#### Post date: [September 1, 2020, 6:14am UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/18 "2020-09-01T06:14:53Z")
The badge in the README still links to 0.1.0. Is there a way to get a “latest release”-link and use that one?
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [September 1, 2020, 7:28am UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/19 "2020-09-01T07:28:39Z")
There’s meant to be an action that creates the stable docs and triggers when tags get pushed to the repo, but it appears that if another action (TagBot) is what pushes the tag then the second action doesn’t happen. [https://github.community/t/github-actions-workflow-not-triggering-with-tag-push/17053](https://github.community/t/github-actions-workflow-not-triggering-with-tag-push/17053) suggests that a personal access token is what’s needed.
---
### Author:  [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)
#### Post date: [September 1, 2020, 9:09am UTC](https://discourse.julialang.org/t/ann-publish-jl/45500/20 "2020-09-01T09:09:53Z")
See the note on _“TagBot & tagged versions”_ here: [Hosting Documentation · Documenter.jl](https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#GitHub-Actions).
[Next page](https://discourse.julialang.org/t/ann-publish-jl/45500.md?page=2)