• FAQ
+
+# My Projects
-# 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).
+### Still have to update this section.