This package is not yet published to the general Julia registry. So in the
meantime if you want to use it, you'll need to clone this repo and then "dev it"
into your local Julia project. I hope to publish it soon once I've worked out
any remaining kinks related to the -m
flag in Julia 1.12.
I developed this package as a general purpose tool for running
Literate.jl
on collections of
files to generate Markdown (and, optionally, Jupyter notebooks). This tool is
primarily meant to be used in conjunction with static site generators. It
transforms Julia files into Markdown which can then be translated by any number
of static site tools into HTML to be published.
Much, if not all, of this could be done using Documenter.jl directly. But in cases where one wants to publish via other tools, this makes the generation of the Markdown quite easy. Example use cases include:
- Generating a
README.md
for agit
repository directly from Julia code. - Generating Markdown to inject into a Jekyll site.
- Generating Markdown for use with
retype
- Generating Markdown for use with
slidev
- Use with any other static site generator that accepts Markdown
These instructions assume you are using Julia v1.12 which, at this time,
has not yet been released. So until Julia v1.12 is released, you'll need to
use juliaup
to first include the nightly builds with juliaup add nightly
and then when you run julia
, invoke it with julia +nightly
.
Also note that Runlit
must be installed in your projects environment (whatever
that is) along with any other dependencies you might have.
In addition, as with all things Julia, you need to understand that the first time you run something you'll trigger JIT (pre-) compilation. So if you have the occasional hiccup when doing something for the first time be patient. Once Julia has done its JIT thing, things will be super fast.
Running julia -m Runlit -h
by itself will give you more information about command
line options. Current options are:
optional arguments:
-f, --force force updating of all input files
-c, --code show code only, do not execute
--notebook genereate notebook files as well
-e, --ext EXT file extension associated with input files
(default: ".jl")
-i, --input INPUT directory to search for input files
-o, --output OUTPUT directory where output files should be written
-h, --help show this help message and exit
Here are some quick notes on how to start using Runlit
with the
retype
and Slidev (both of which I
highly recommend).
As a general note, Runlit
is designed to work with static site generators that
take Markdown as their input. So the general process here is going to involve:
- Writing Julia code which
Runlit
will convert into Markdown - Running a static site generator that transforms the Markdown into HTML
- Publishing the HTML somewhere.
This means that there will ultimately be three different directories involved. One to hold the Julia source code, one to hold the Markdown source code and one to hold the HTML.
For retype
, you'll need to install retype
(see
here on how to do that).
Everything discussed here can be found in the examples/retype
directory. In
fact, you can just go to that directory and type julia --project=. -m Runlit -i src -o markdown
to generate the Markdown for it.
Then you'll need to figure out how you want to organize your site content. There
are many configuration options for retype
, but my suggestion is to create
a new Julia project, e.g.,
$ julia -e 'using Pkg; Pkg.generate("<ProjectName>")'
But however you choose to initialize your directory (it doesn't have to be a Julia project at all), I suggest the following directory structure:
src
to hold your Julia source codemarkdown
- to hold the generated Markdownsite
- to hold the generate site source code
You'll want to create these directories but most likely you'll want to put
markdown
and site
in your .gitignore
file since they will contain
generated files not source files. You may want to version control the
markdown
directory if your CI/CD pipeline (that publishes the site) isn't
Julia aware. This way you won't need Julia at all in your CI/CD environment.
For this configuration, the following retype.yml
configuration file will
suffice and should be placed in the projects root directory:
input: markdown
output: site
url: example.com # Add your website here
branding:
title: Julia + Retype
label: Docs
links:
- text: Getting Started
link: https://retype.com/guides/getting-started/
footer:
copyright: "© Copyright . All rights reserved."
If your Julia code uses any third party libraries, be sure to add them to the
Project.toml
file (or, even better, press ]
in the julia
REPL and use the
pkg>
prompt to add
them, e.g., pkg> add Plots
).
Please note if you do depend on third party libraries (and, therefore, you
have your own Project.toml
file distinct from the global Julia environments),
you need to be sure to add Runlit
to your Project.toml
as well.
At this point, if you have Runlit
installed in your Julia environment, you can
just run julia -m Runlit -i src -o markdown
. That will convert the Julia code
to Markdown. You could then run retype build
to then transform the Markdown
to HTML. However, you could also do this:
$ julia -m Runlit -i src -o markdown -e 'retype build'
This command will convert your Julia to markdown and then run the command
retype build
which will regenerate the HTML. So this represents the complete
Julia -> HTML processing step (potentially useful in CI/CD pipelines, for
example).
It is quite common to want to preview the results as you document. You can do
this a number of different ways. The first thing to know about is the --watch
(or -w
for short) flag which will keep Runlit
running and regenerating
Markdown whenever there is a change in your source directory, e.g.,
$ julia -m Runlit -i src -o markdown -w
You can combine this with the -e
flag as follows:
$ julia -m Runlit -i src -o markdown -w -e 'retype build'
The you can keep a browser open to the generated HTML and just hit refresh to
see the latest version. But an alternative is to simple run Runlit
without
the -e
flag and, in a separate shell, run retype start
. This has a number
of benefits:
- The
retype
process never shuts down so it responds much quicker to changes (because it won't regenerate the whole site, just update the files that changed). - It will open the browser for you.
- It runs its own server that will cause the page to automatically reload whenever the HTML code is updated (so you don't have to keep reloading manually)
Many static site generators use "front-matter" (YAML metadata included at the start of the Markdown code) to guide site generation. This is not an issue for Literate.jl, just include a block like this at the top of your Julia file:
# ---
# label: Page Title
# ---
In the case of Slidev, you need to create an npm
project
for your work (instructions on doing this can be found
here).
Once you have a Slidev project (i.e., a directory with a package.json
file
in it), you can turn that same directory into a Julia project. In such a
configuration, the package.json
and Project.toml
files will be in the same
directory.
Note that Slidev expects your slides to be contained in slides.md
in the root
directory. So a basic configuration would be to mkdir a directory called src
and in that directory include a file called slides.jl
.
$ julia -m Runlit -i src -o .
...in the directory with Project.toml
in it and Runlit
will generate your
slides.md
file for you.
If you want to test this out, you can run this in the examples/slidev
directory. But since it uses third party libraries, you need to run this
command:
$ julia --project=. -m Runlit -i src -o .
The site itself can be generated with npm run build
. Using the -e
flag, we
can regenerate the HTML each time the Markdown is updated (i.e., when the
Julia files are updated) with:
$ julia -m Runlist -i src -o . -e 'npm run build'
To preview the slides with hot reloading of the web page, don't use the -e
flag above but, instead, run the following command in a different shell:
$ npm run dev