Working with Franklin

Set things up in minutes and focus on writing great content.

Creating your website

To get started, the easiest is to use thenewsite function to generate a website folder which you can then modify to your heart's content. The command takes one mandatory argument: thename 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 ofsimple templates you can choose from and tweak.

⚠ Note

The templates are meant to be used asstarting 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 tonewsite generates a folder with the following structure:

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

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

the files in the top folder such asindex.md are the source files for the generated pages, you must have anindex.md orindex.html at the top level but can then use whatever folder structure you want (see further),
you shouldnot modify the content of__site as it'sgenerated and any changes you do in there may be silently over-written whenever you modify files elsewhere,
the folders_assets/,_libs/,_layout and_css containauxiliary 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,

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 specifying 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 anindex.html file instead of generating it via theindex.md. You will still need to put it in the exact same place and let Franklin copy the files appropriately.

Note that Franklin generates a folder structure in__site which allows having 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 having the following URLs:

[website]/
[website]/page/
[website]/folder/subpage/

Reserved names

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

/css/ or/css.md
/layout/ or/layout.md
/literate/ or/literate.md

Also bear in mind that Franklin will ignoreREADME.md,LICENSE.md,Manifest.toml andProject.toml (Manifest.toml andProject.toml are still copied to the output directory).

Tag pages

All pages with a given tag can be found (by default) at[website]/tag/<tag_name>. The tag page location can be changed by setting thetag_page_path variable inconfig.md. For example, setting@def tag_page_path = "my_tags" would cause tag pages to appear at[website]/my_tags/<tag_name>.

Editing and testing your website

Theserve 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 bareboneserve(), do?serve in your REPL for all options, we list a few noteworthy ones below:

clear=false, whether to erase__site and start 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 theoptimisation 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 thanverb=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 theverify_links(). It will take a few seconds to verify all links on every generated page 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 ✓.

⚠ Note

This functionality is pretty rudimentary and while it might help you to find internal dead links, for serious work you might still want to do a second pass with a well-established link-checker such asbroken-link-checker.

Pre-rendering and compression

Theoptimize function can

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 stepsmay lead to faster loading pages. Note that in order to run them, you will need a couple of external dependencies as mentioned in theinstallation section.

⚠ Note

The minifier script (an external python lib) used is far from perfect and can break your website, generally speaking, if things work locally but not when you deploy, try disabling it withoptimize(minify=false).

Also note that if you use GitHub or GitLab pages, the minification is not needed as these platforms compress the pages themselves.

Publish

⚠ Note

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

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

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

See?publish for more information.

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

+++prepath = "project"+++

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

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

Movatterモバイル変換