jwebsite/workflow/index.md

Working with Franklin

\blurb{Set things up in minutes and focus on writing great content.}

\lineskip

\toc

Creating your website

To get started, the easiest is to use the newsite function to generate a website folder which you can then modify to your heart's content. The command takes one mandatory argument: the name of the folder (which can be "." if you want to set things up in your current directory). You can optionally specify a template:

julia> newsite("TestWebsite"; template="vela")
✓ Website folder generated at "TestWebsite" (now the current directory).
→ Use serve() from Franklin to see the website in your browser.

There are a number of simple templates you can choose from and tweak.

\note{The templates are meant to be used as starting points and will likely require some fixes to match what you want. Your help to make them better is very welcome.}

Once you have created a new website folder, you can start the live-rendering of your website with

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

and navigate in a browser to the corresponding address to preview the website.

Folder structure

The initial call to newsite generates a folder with the following structure:

.
├── _assets/
├── _layout/
├── _libs/
├── config.md
└── index.md

After running serve the first time, an additional folder is generated: __site which will contain your full generated website. Among these folders:

@@tlist

• the files in the top folder such as index.md are the source files for the generated pages, you must have an index.md or index.html at the top level but can then use whatever folder structure you want (see further),
• you should not modify the content of __site as it's generated and any changes you do in there may be silently over-written whenever you modify files elsewhere,
• the folders _assets/, _libs/, _layout and _css contain auxiliary files supporting your site:
  • _assets/ will contain images, code snippets, etc.,
  • _css/ will contain the style sheets,
  • _libs/ will contain javascript libraries,
  • _layout/ will contain bits of HTML scaffolding for the generated pages, @@

Top folder

In this folder,

@@tlist

• index.md will generate the site's landing page,
• pages/page1.md would correspond to pages on your website (you can have whatever subfolder structure you want in here),
• config.md allows to specify variables that help steer the page generation, you can also use it to declare global variables or definitions that can then be used on all pages. @@

\note{You can also write pages in plain HTML. For instance you may want to write an index.html file instead of generating it via the index.md. You will still need to put it at the exact same place and let Franklin copy the files appropriately.}

Note that Franklin generates a folder structure in __site which allows to have URLs like [website]/page1/. The following rules are applied:

• the filename is [path/]index.md or [path/]index.html, it will be copied over "as is" to __site/[path/]index.html,
• the filename is [path/]somepage.md or [path/]somepage.html, it will be copied to __site/[path/]somepage/index.html.

So for instance if we ignore auxiliary files and you have

.
├── index.md
├── folder
│   └── subpage.md
└── page.md

it will lead to

__site
  ├── index.html
  ├── folder
  │   └── subpage
  │       └── index.html
  └── page
      └── index.html

which allows to have the following URLs:

@@tlist

• [website]/
• [website]/page/
• [website]/folder/subpage/ @@

Reserved names

To avoid name clashes, refrain from using the following paths where / indicates the topdir (website folder):

@@tlist

• /css/ or /css.md
• /layout/ or /layout.md
• /literate/ or /literate.md @@

Also bear in mind that Franklin will ignore README.md, LICENSE.md, Manifest.toml and Project.toml.

Editing and testing your website

The serve function can be used to launch a server which will track and render modifications. There are a few useful options you can use beyond the barebone serve(), do ?serve in your REPL for all options, we list a few noteworthy one below:

@@tlist

• clear=false, whether to erases __site and starts from a blank slate,
• single=false, whether to do a single build pass generating all pages and not start the server.
• prerender=false, whether to prerender code blocks and maths (see the optimisation step)
• verb=false, whether to show information about which page is being processed etc,
• silent=false, whether to suppress any informative messages that could otherwise appear in your console when editing your site, this goes one step further than verb=false as it also applies for code evaluation,
• eval_all=false, whether to re-evaluate all code blocks on all pages. @@

Post-processing

Verify links

Before deploying you may want to verify that links on your website lead somewhere, to do so use the verify_links(). It will take a few second to verify all links on every generated pages but can be quite helpful to identify dead links or links with typos:

julia> verify_links()
Verifying links... [you seem online ✓]
- internal link issue on page index.md: /menu3/.

then after fixing and re-generating pages:

julia> verify_links()
All internal and external links verified ✓.

Pre-rendering and compression

The optimize function can

@@tlist

• pre-render KaTeX and highlight.js code to HTML so that the pages don't have to load these javascript libraries,
• minify all generated HTML and CSS. @@ See ?optimize for options.

Those two steps may lead to faster loading pages. Note that in order to run them, you will need a couple of external dependencies as mentioned in the installation section.

The optimize function is called by default in the publish function which can be used to help deploy your website.

Publish

\note{If you use GitHub or GitLab with a deployment action on those platforms, you do not need to use publish, you can just push your changes and let the relevant action do the rest on the platform. See the section on deployment.}

Once you have synched your local folder with a remote repository (see deployment instructions), the publish function can be called to deploy your website; it essentially:

@@tlist

• applies an optional optimisation step (see previous point),
• does a git add -A; git commit -am "franklin-update"; git push. @@

See ?publish for more information.

In any case, before deploying, if you're working on a project website i.e. a website whose root URL will look like username.gitlab.io/project/ then you should add the following line in your config.md file:

@def prepath = "project"

the publish function will then ensure that all links are fixed before deploying your website.

Note also that the publish function accepts a final= keyword to which you can pass any function () -> nothing to do some final post-processing before pushing updates online. For instance, you can use final=lunr where lunr is a function exported by Franklin which generates a Lunr search index (see this tutorial for more details).