# 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-repl 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](https://tlienart.github.io/FranklinTemplates.jl/) 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-repl 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: ```plaintext . ├── _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](#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-repl julia> verify_links() Verifying links... [you seem online ✓] - internal link issue on page index.md: /menu3/. ``` then after fixing and re-generating pages: ```julia-repl 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](/index.html#installing_optional_extras). 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](/workflow/deploy/).} Once you have synched your local folder with a remote repository (see [deployment instructions](/workflow/deploy/)), 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: ```markdown @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](/extras/lunr/) for more details).