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

#1

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.

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.

27 Likes
#2

Nice! Is there an example web-page?

#3

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).

2 Likes
#4

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!

1 Like
#5

Done, thanks

#6

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.

#7

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.

1 Like
#8

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

1 Like
#9

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.

3 Likes
#10

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

1 Like
#11

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$

\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$

* 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.

#12

Awesome!

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

#13

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 :))

1 Like