[ANN] JuDoc.jl: a static site generator in Julia

[tlienart]

Hi,

JuDoc.jl is a simple static site generator (SSG) for Julia with a focus on simplicity, technical blogging and light, fast-loading pages.
It is inspired from an older simple SSG: Jemdoc (in python).

There’s a multitude of SSGs out there so why should you bother with this one? Here are a few reasons you may want to consider:

• it allows LaTex-like definition of commands which effectively allows you to extend markdown almost without limits; the definition of those commands can be made of markdown, HTML and/or other LaTeX-like commands.
• first class support for KaTeX (for maths) and highlight.js (for code) with the possibility to pre-render the corresponding javascript.
• support for hyperreferences both for equations (\eqref{...}) and references (\cite{...}).
• a simple templating system to adjust and interact with the layout.
• live rendering of modification (via LiveServer.jl) and fast page updating (a few milliseconds in a warm session).

Of course the package is still fairly young and rough around the edges (though I’ve been using it for a while) but I hope that with user feedback and suggestions it could become nice. See also how you could help.

Edit: as per comments, here is probably a point where you may want to know what it could look like, there are a few templates that are available and should be easily customisable (see here); I use a basic one for my website). Help to add more templates is more than welcome

Giving it a shot

The package was recently registered so you can just add JuDoc and do

julia> using JuDoc
julia> newsite("test", template="pure-sm")
✓ Website folder generated at "test" (now the current directory).
→ Use serve() from JuDoc to see the website in your browser.

julia> serve()
→ Initial full pass...
→ Starting the server...
✓ LiveServer listening on http://localhost:8000/ ...
  (use CTRL+C to shut down)

This will generate a folder test in your current directory and its rendered content can be viewed at the given URL in your browser. Open test/src/index.md in an editor and modify it at will while keeping an eye in your browser to get a feel for what the package can do.

Head to the docs for more information on the syntax etc.

What JuDoc is and isn’t

JuDoc hopes to sit somewhere between Documenter.jl and Weave.jl. Unlike Weave.jl however, JuDoc will not live-execute code which would slow down the page generation.(*) It does however support a simple system to insert code and code output while ensuring things don’t go stale (see the docs on insertions).

JuDoc is also not meant to be a contender to major “do-it-all” SSGs like Hugo or Jekyll, in particular if you want to have a blog mostly with images and text, then JuDoc is probably not going to be super useful to you (unless the “it’s in Julia” factor is sufficiently convincing). However if you want a website that’s easy to tune and where you can write technical notes using a blend of LaTeX and Markdown then JuDoc could fit the bill.

Finally it’s very much a static site generator; if you would like interactivity, there are already a number of great Julia packages out there for web apps such as Bukdu.jl or Genie.jl.

Comments and suggestions are very welcome!

PS: thanks to @asprionj for early feedback and convincing me to push this first release over the line.

PPS (*) actually now it does allow evaluation of code following requests though of course it’s not as mature as weave.

[mauro3]

Nice! Is there an example web-page?

[tlienart]

Yeah sure! well the quickstart with newsite will be an example webpage. But if you want something less toyish and already live I guess a random page from my website? (edit: the source for that page can be seen here).

[thofma]

You should add your homepage as an example to the documentation/README (usually one first wants to see an example without installing the package.)

P.S.: This looks very nice!

[tlienart]

Done, thanks

[asprionj]

Congrats on this first release!
Wish I could have helped or at least provided further testing/feedback during the last weeks.

Extending the question of @mauro3: It would be awesome to have a standard example page in all currently available layouts/styles somwhere; ideally as pages in a (sub-)section of the docs. I do know myself, so others probably handle decisions on what to spend time similarly: I look at what something can produce, and only if this looks “good” in any way (nice, beautiful, cool, interesting, fun, …) I have a deeper look at the actual thing.

[tlienart]

Yep that’s fair enough, in the docs there’s a table with the currently available templates + link to what it looks like but I guess generating example pages for the various templates & and linking to them would be neat.

[PetrKryslUCSD]

What would happen if I gave your package the text of a book typeset in LaTeX? Should I expect this to work?

[tlienart]

It will need a bit of help:

• all commands outside of maths environment will need to be defined so for instance if you use \textbf{...} in the text you would need to have \newcommand{\textbf}[1]{**#1**}. Provided the command can be described in markdown or HTML, it can be used,
• all non-maths environments like \begin{figure} ... \end{figure} would have to be replaced by div blocks of the form @@fig ... @@ (see the docs), these blocks can then be styled with CSS,
• expressions such as {\emph ... } would need to be replaced by \emph{...}

But apart from that it should mostly work. If you were interested in doing this I’d gladly give you a hand.
I might also write a small tool to help going from a .tex file to a corresponding .md file.

[yakir12]

I’ll just mention pandoc that excels in those kind of conversions. Might save you some time.

[tlienart]

Thanks, I think here Pandoc may be a bit overkill as it’s not the full .tex that would have to be transformed but rather only the commands that aren’t yet defined and also the rules would not be standard TEX->HTML & you’d want to keep control over how they are translated. Possibly all this could be done with Pandoc but I’m not entirely sure it would be much easier / faster

So for instance

\documentclass{article}
\usepackage{xcolor}

\begin{document}

\section{Introduction}
Here is the text of your introduction.

\[
\exp(i\pi)+1 = 0
\]

\subsection{Subsection Heading Here}
Write your subsection text here.

\begin{itemize}
	\item first item
	\item second item
\end{itemize}

etc \textbf{done} and \textcolor{blue}{hello}.

\end{document}

Would be converted to

\newcommand{\section}[1]{# #1}
\newcommand{\subsection}[1]{## #1} 
\newcommand{\textbf}[1]{**!#1**}
\newcommand{\textcolor}[2]{~~~ <font color="#1">#2</font> ~~~}

\section{Introduction}

Here is the text of your introduction.

\[
\exp(i\pi)+1 = 0
\]

\subsection{Subsection Heading Here}

Write your subsection text here.

* first item
* second item

etc \textbf{done} and \textcolor{blue}{hello}.

This is not very hard to do within the current package and I would assume would potentially require more effort from within PanDoc because you’d need to define all the rules anyway.

In any case I think what could be useful is to define “standard latex commands” and have those directly available to the user which would reduce the number of commands you’d end up having to define yourself.

[Wenjie]

Awesome!

How is it different from Jekyll? And could you please show some example of non-inline code?

[tlienart]

Thanks!

I haven’t done a detailed comparison with other SSGs. But I imagine the answer when compared to big ones like Jekyll and Hugo is: it’s simpler. Though of course that also means that it’s got fewer features.
An aim is to force the user as little as possible to have to learn a lot of new stuff in order to get a simple website, and so hopefully it’s quite intuitive how to modify the website layout etc.

Another noteworthy difference is the syntax. While the base syntax is also plain markdown so that you could pretty much copy paste Jekyll pages into a Judoc folder (this is what @cormullion did with his website recently btw), the extensions are different and here the idea is to imitate LaTeX for command definition. See the syntax.

I’m not sure what you mean with non inline code but you could have a look at the docs for more examples (or open an issue if you’d like help with something :))

[cserteGT3]

I’m not sure this is the right time to ask (as I just started experimenting with the package), but interested if I can do the following (or how to do it to be exact):
I’d like to have some data in a .csv file, that I update every day (let’s say the average temperature of that day). I want to plot this data, and do some calculations (as complex as average, min/max, etc.) and have a line the says: this is the max temperature and also a bit of text about this temperature project
Of course all of this as part of my personal page (importing from jekyll).
As the docs states I can use Literate.jl seamlessly with this package, but don’t understand it completely.
Or should I just Weave.jl and after updating the csv file, weave the source into an html page? Or using Literate.jl would be the same workflow?

[tlienart]

Hello,

On master you can now also directly evaluate Julia code blocks on the fly similar to weave which is what it looks like you want to do, the only hiccup is that the generation of the page where the plot is will be slowed down significantly by the drawing of the plot due to time to first plot issue.

If you open an issue on JuDoc with an example CSV and plotting script I can show you how to do it and will be glad to have feedback

Edit: for instance with dummy data (good old faithful) it looks like this

This would be in the markdown describing the page, the code below will be displayed and executed:

```julia:oldfaithful/plt
using PyPlot, DelimitedFiles
d = readdlm(joinpath(@__DIR__, "data.dat"))
figure()
scatter(d[:,1],d[:,2])
savefig(joinpath(@__DIR__, "plot.png"))
```

![the plot](/assets/oldfaithful/plot.png)

Here’s a screenshot:

You could also hide the code if you wanted, etc but I guess this would be better discussed on an issue to not spam everyone.

Note: this is recently added feature so feedback is welcome to make it better / less error-prone.

[cserteGT3]

Thank you for the example!
For anyone interested in this usecase, the follow up discussion is here, (with examples for Weave.jl and Literate.jl too).