diff --git a/README.md b/README.md
index 64bed2a74..f2e89ccde 100644
--- a/README.md
+++ b/README.md
@@ -20,9 +20,9 @@
Franklin is a simple **static site generator** (SSG) oriented towards technical blogging (code, maths, ...), flexibility and extensibility.
-The base syntax is plain markdown with a few extensions such as the ability to define and use LaTeX-like commands in or outside of maths environments and the possibility to evaluate code blocks on the fly.
+The base syntax is plain markdown with a few extensions such as the ability to define and use LaTeX-like commands in or outside of maths environments and the possibility to evaluate code blocks on the fly.
-Franklin has a channel **#franklin** on the Julia slack, this is the best place to ask usage question.
+Franklin has a channel **#franklin** on the Julia slack, this is the best place to ask usage questions.
**Note**: I'm looking for people with web-dev chops who would be keen to help improve and enrich the base themes available at [FranklinTemplates.jl](https://github.com/tlienart/FranklinTemplates.jl), even if you're not super confident in Julia. More generally, if you would like to work on something or fix something in either Franklin or FranklinTemplates, please reach out on Slack, I will gladly help you get started.
@@ -128,7 +128,7 @@ alias franklin=julia -O0 -e 'using Franklin; serve()'
While Franklin broadly supports standard Markdown there are a few things that may trip you which are either due to Franklin or due to Julia's Markdown library, here are key ones you should keep in mind:
* when writing a list, the content of the list item **must** be on a single line (no line break)
-* you can write comments with `` the comment markers `` **must** be separated by a character that is not a `-` to work properly so `` is ok but `` is not, best is to just systematically use a whitespace: ``.
+* you can write comments with `` the comment markers `` **must** be separated by a character that is not a `-` to work properly so `` is ok but `` is not, best is to just systematically use whitespace: ``.
* be careful writing double braces, `{{...}}` has a *meaning* (html functions) this can cause issues in latex commands, if you have double braces in a latex command, **make sure to add whitespaces** for instance write `\dfrac{1}{ {101}_{2} }` instead of `\dfrac{1}{{101}_{2}}`. In general use whitespaces liberally to help the parser in math and latex commands.
* (as of `v0.7`) code blocks should be delimited with backticks `` ` `` you *can* also use indented blocks to delimit code blocks but you now have to **opt in** explicitly on pages that would use them by using `@def indented_code = true`, if you want to use that everywhere, write that in the `config.md`. Note that indented blocks are **ambiguous** with some of the other things that Franklin provides (div blocks, latex commands) and so if you use them, you are responsible for avoiding ambiguities (effectively that means _not using indentation for anything else than code_)
diff --git a/docs/code/eval-tricks.md b/docs/code/eval-tricks.md
index e710f370d..039de15a4 100644
--- a/docs/code/eval-tricks.md
+++ b/docs/code/eval-tricks.md
@@ -12,7 +12,7 @@ reviewed: 22/12/2019
\toc
-The basic idea is to exploit the fact that the output of a Julia code block evaluated by Franklin can be re-processed as Franklin Markdow when using the `\textoutput` command; this offers a wide range of possibilities best shown through a few examples (more or less in increasing degree of sophistication).
+The basic idea is to exploit the fact that the output of a Julia code block evaluated by Franklin can be re-processed as Franklin Markdown when using the `\textoutput` command; this offers a wide range of possibilities best shown through a few examples (more or less in increasing degree of sophistication).
## Generating a table
@@ -93,7 +93,7 @@ println("@@")
### Code
-That can obtained with (see detailed explanations further below)
+That can be obtained with (see detailed explanations further below)
```html
\newcommand{\circle}[1]{
@@ -124,7 +124,7 @@ println("@@")
The first part defines a command `\circle` which takes one argument for the fill colour and inserts SVG code for a circle with that colour.
The second part is a Julia code block which will be evaluated but not displayed on the page (since there is a `#hideall`).
-The code loops over the each colour `c` and prints `\circle{c}` so that the code block effectively generates:
+The code loops over each colour `c` and prints `\circle{c}` so that the code block effectively generates:
```plaintext
@@ccols \circle{pink}...\circle{yellow}@@
@@ -150,7 +150,7 @@ The last thing to do is to style the `colors` div appropriately:
You may want to have a page with responsive team cards for instance where every card would follow the same layout but the content would be different.
There are multiple ways you can do this with Franklin and a simple one below (adapted from [this tutorial](https://www.w3schools.com/howto/howto_css_team.asp)).
-The advantage of doing something like this is that it can help separate the content from the layout making both arguably easier more maintainable.
+The advantage of doing something like this is that it can help separate the content from the layout making both arguably easier and more maintainable.
### Preview
diff --git a/docs/code/index.md b/docs/code/index.md
index 700cddec9..87bbdbd36 100644
--- a/docs/code/index.md
+++ b/docs/code/index.md
@@ -20,7 +20,7 @@ As per Common Mark specifications, you have multiple ways of inserting code:
This is some `inline code` or ``inline ` code with a tick``.
`````
-**Note**: To use backslash (`\ `) at the end of inline code, you must include a trailing space to ensure the trailing tick is parsed correctly, eg `` `some code with \ ` ``. The trailing space will be trimmed in the rendered html.
+**Note**: To use a backslash (`\ `) at the end of the inline code, you must include a trailing space to ensure the trailing tick is parsed correctly, eg `` `some code with \ ` ``. The trailing space will be trimmed in the rendered html.
* **code blocks**: it is recommended to use triple backticks (\`\`\`) optionally followed by a language name for highlighting like so:
@@ -45,8 +45,8 @@ This is some code:
### Evaluating code
-When presenting code in a post, it's often convenient to have a way to check the code works and the output shown corresponds to the code.
-In Franklin there are two approaches that help you for this:
+When presenting code in a post, it's often convenient to have a way to check that the code works and that the output shown corresponds to the code.
+In Franklin, there are two approaches that help you with it:
@@tlist
1. For Julia code, a **live-evaluation** of code blocks is supported,
@@ -57,11 +57,11 @@ In Franklin there are two approaches that help you for this:
## Live evaluation (Julia)
-Julia code blocks can be evaluated on the fly and their output either displayed as code or re-interpreted as Markdown.
+Julia code blocks can be evaluated on the fly and their output is either displayed as code or re-interpreted as Markdown.
\note{
**Evaluation time**: when a code block is created or modified and the page is saved, it will trigger a page build that will _wait_ for the evaluation of the code block to complete. So if your code block takes a long time to execute, the page will not be updated before that's done.
- That being said, if you don't modify the code block, it will only be executed **once** as the output is saved to file.
+ That being said, if you don't modify the code block, it will only be executed **once** as the output is saved to a file.
}
Code blocks that _should not_ be evaluated should be added as per standard markdown, so for instance:
@@ -88,8 +88,8 @@ What this will do is:
1. run the code and capture its output (`STDOUT`) and write it to `/assets/[subpath]/code/output/ex1.out`
@@
-The `[subpath]` here is the _exact same sub-path structure_ than to the page where the code block is inserted.
-To clarify, let's say you wrote the above code-block in
+The `[subpath]` here is the _exact same sub-path structure_ as the page where the code block is inserted.
+To clarify, let's say you wrote the above code block in
```
/folder1/page1.md
@@ -103,7 +103,7 @@ then with the syntax above, the script will be saved in
### More on paths
-There are three ways you can specify where the script corresponding to a code-block should be saved.
+There are three ways you can specify where the script corresponding to a code block should be saved.
@@tlist
1. _relative to the page_: `./[p]/script` is as above, it will write the code block to `/assets/[subpath]/p/script.jl` where `subpath` corresponds to the sub-path of the page where the code block is inserted (path below `/src/`)
@@ -143,7 +143,7 @@ and will look like
dot(a, a) = 14
```
-If you now change the vector `a` in the code block, the page will be re-compiled with the code-block re-evaluated and the new output will be shown.
+If you now change the vector `a` in the code block, the page will be re-compiled with the code block re-evaluated and the new output will be shown.
If you would like the output to be re-interpeted by Franklin as text, you can use `\textoutput` instead.
Here's an example:
@@ -273,30 +273,30 @@ savefig(joinpath(@OUTPUT, "sinc.svg")) # hide
\fig{sinc}
-**Note**: observe that here everything is done with relative paths, `pyplot1` is placed in the `/assets/` folder relatively to the path of the current page and the `\fig` since it's given a path that doesn't start with `/` or `./` will also look in that folder to try to find a figure which starts with the name `sinc`. See also [more about paths](#more_on_paths).
+**Note**: observe that here everything is done with relative paths, `pyplot1` is placed in the `/assets/` folder relatively to the path of the current page and the `\fig` since it's given a path that doesn't start with `/` or `./` will also look in that folder to try to find a figure which starts with the name `sinc`. See also [more about paths](#more_on_paths).
**Note**: If you wish to use `Plots.jl` and deploy to GitHub pages, you will need to modify the `.github/workflows/Deploy.yml` by adding `env: GKSwstype: "100"` before the ` - name: Build and Deploy` line. [Here](https://github.com/storopoli/Bayesian-Julia/blob/master/.github/workflows/Deploy.yml) is an example.
### Troubleshooting
-A few things can go wrong when attempting to use and evaluate code blocks.
-The first thing to do if no output is shown or an error appears is to make sure that:
+A few things can go wrong when attempting to use and evaluate code blocks.
+The first thing to do when no output is shown or when an error appears is to make sure that:
@@tlist
1. if the code uses packages, these packages are available in the local environment,
1. the code "just works" in the REPL.
@@
-If this is the case and you still have issues, then you may want to force re-evaluation of the code on the page.
+If this is the case and you still have issues, then you may want to force a re-evaluation of the code on the page.
In such a case, try adding `@def reeval = true` on the page which will cause **all** code blocks on the page to be completely re-evaluated and their output re-generated.
-Assuming that helped, you will then want to remove that line as otherwise that page will be fully re-evaluated _every single time the page is modified_ which will cause an unnecessary overhead.
+Assuming that helped, you will then want to remove that line as otherwise that page will be fully re-evaluated _every single time the page is modified_ which will cause unnecessary overhead.
**Important note**: unless you explicitly use `@def reeval = true`, code blocks are evaluated *only* if:
@@tlist
- an earlier code block has been evaluated (in which case, since their results may depend on it, all subsequent blocks are re-evaluated),
- the content of the code block has changed.
@@
-An example where this can be a bit tricky is if your code block calls a function on a file, for instance `read(file, String)`; if the underlying *file* is changed, the code block will **not** be re-evaluated (since the code doesn't change), so in such cases you will want to use a `@def reeval = true`.
+An example where this can be a bit tricky is if your code block calls a function on a file, for instance `read(file, String)`; if the underlying *file* is changed, the code block will **not** be re-evaluated (since the code doesn't change), so in such cases, you will want to use a `@def reeval = true`.
## Offline evaluation (any language)
@@ -305,7 +305,7 @@ The philosophy here is:
@@tlist
* keep your code snippets in appropriate subfolders of `/assets/` where they can be run and their output can be saved, this can be compared to a `test/` folder in a Julia package,
* run some or all of the snippets (before running Franklin),
-* use `\input{...}{...}` in your markdown (see below) and when the website is updated, it will plug-in the most recent parts that have been generated.
+* use `\input{...}{...}` in your markdown (see below) and when the website is updated, it will plug in the most recent parts that have been generated.
@@
That way, if you modify the code, everything will be updated on the website too while ensuring that the code actually runs and generates the output you're displaying.
@@ -368,7 +368,7 @@ In order to insert the plain-text output of a script, you can use
\output{scripts/script1.jl}
```
-This will insert the content of the file `/assets/scripts/script1.out` into a non-highlighted code-block.
+This will insert the content of the file `/assets/scripts/script1.out` into a non-highlighted code block.
### Plot output
@@ -386,4 +386,4 @@ The `plot:id` option is useful if you have a script that generates several plots
### Slicing up
The structure in the `generate_results.jl` effectively means that all your code is run as one big script.
-This also means that if you want to slice some of your code in several parts and show intermediate outputs (e.g. plots), you can just do that by having a `script_1_p1.jl`, `script_1_p2.jl` etc. and then just use `\input` multiple times.
+This also means that if you want to slice some of your code into several parts and show intermediate outputs (e.g. plots), you can just do that by having a `script_1_p1.jl`, `script_1_p2.jl` etc. and then just use `\input` multiple times.
diff --git a/docs/extras/index.md b/docs/extras/index.md
index 09413cac9..bb427869d 100644
--- a/docs/extras/index.md
+++ b/docs/extras/index.md
@@ -1,12 +1,12 @@
# Extras
-In this section of the manual, the assumption is that you already have a fairly good idea of how Franklin works so that basic explanations are skipped (refer to the rest of the manual for help).
+In this section of the manual, the assumption is that you already have a fairly good idea of how Franklin works so basic explanations are skipped (refer to the rest of the manual for help).
-The aim is to show how Franklin can work with other useful libraries to add functionalities to your website.
+The aim is to show how Franklin can work with other useful libraries to add functionalities to your website.
See also the [demos](/demos/).
-As usual, these examples are just meant to show what can be done, not the best way to do it, feel free to modify the examples at will!
-Also, if you come up with other nice ways of extending Franklin, don't hesitate to make a suggestion for an example to be added here.
+As usual, these examples are just meant to show what can be done, not the best way to do it, feel free to modify the examples at will!
+Also, if you come up with other nice ways of extending Franklin, don't hesitate to make a suggestion for an example to be added here.
## List of examples
diff --git a/docs/extras/literate.md b/docs/extras/literate.md
index 15cde4895..76be81d11 100644
--- a/docs/extras/literate.md
+++ b/docs/extras/literate.md
@@ -4,10 +4,10 @@
See also [how to interact with literate scripts](/code/literate/).
-[Literate.jl](https://github.com/fredrikekre/Literate.jl) allows to pre and post-process a script in order, for instance, to generate a notebook out of a script.
-This can be convenient if you want to have a tutorial be downloadable as a standalone notebook or as a scrubbed script.
+[Literate.jl](https://github.com/fredrikekre/Literate.jl) allows to pre and post-process a script in order, for instance, to generate a notebook out of a script.
+This can be convenient if you want to have a tutorial downloadable as a standalone notebook or as a scrubbed script.
-This page presents one way of doing this which is used in [DataScienceTutorials](https://github.com/alan-turing-institute/DataScienceTutorials.jl) and which might inspire your own approach.
+This page presents one way of doing this which is used in [DataScienceTutorials](https://github.com/alan-turing-institute/DataScienceTutorials.jl) and which might inspire your own approach.
The key ingredients are:
@@ -17,13 +17,13 @@ The key ingredients are:
1. add this as a `final` hook to `publish`.
@@
-In what follows, it is assumed you have your Literate scripts in a folder `/scripts/` and that you're using GitHub.
-It shouldn't be hard to modify that to suit your own case.
+In what follows, it is assumed you have your Literate scripts in a folder `/scripts/` and that you're using GitHub.
+It shouldn't be hard to modify that to suit your own case.
## Using Literate to generate auxiliary files
-Literate can manipulate scripts fairly easily, for instance to generate notebooks:
+Literate can manipulate scripts fairly easily, for instance, to generate notebooks:
```julia
scripts = joinpath.("scripts", readdir("scripts"))
diff --git a/docs/extras/lunr.md b/docs/extras/lunr.md
index 76e30322a..8ce386e47 100644
--- a/docs/extras/lunr.md
+++ b/docs/extras/lunr.md
@@ -4,10 +4,10 @@
\toc\skipline
-[`lunr.js`](https://lunrjs.com/) is a neat little Javascript library that allows to equip your website with a search functionality fairly easily.
+[`lunr.js`](https://lunrjs.com/) is a neat little Javascript library that equips your website with a search functionality fairly easily.
The steps below show a simple way of doing this matching what is done on this website.
-Once it's working, you might want to adjust the `build_index.js` and/or the `lunrclient.js` to match your needs.
+Once it's working, you might want to adjust the `build_index.js` and/or the `lunrclient.js` to match your needs.
## Pre-requisites
@@ -27,7 +27,7 @@ $> npm install cheerio
Copy [this folder](https://github.com/tlienart/Franklin.jl/tree/master/docs/_libs/lunr) to a `/_libs/lunr/` directory.
Discard the `lunr_index.js` which is the index of this website, a version for your website will be generated dynamically.
-The important files are `build_index.js` and `lunrclient.js` (of which a minified version is provided which you will want to re-generate if you modify the base file).
+The important files are `build_index.js` and `lunrclient.js` (of which a minified version is provided which you will want to re-generate if you modify the base file).
These files are adapted from [this repository](https://github.com/BLE-LTER/Lunr-Index-and-Search-for-Static-Sites) which shows how to use Lunr on a static website.
You can choose whether to serve your own copy of `lunr.min.js` (done here) or to use an online version via
@@ -43,10 +43,10 @@ The file `build_index.js` does the following:
@@tlist
- it goes over all files in a `HTML_FOLDER` (by default: `/__site/`),
-- it builds an index `lunr_index.js` which can subsequently be queried upon the user entering search terms.
+- it builds an index `lunr_index.js` which can subsequently be queried upon the user entering search terms.
@@
-By default, the index built is fairly barebone to reduce the size of the generated index. If you want fancier search, you might want to modify this a bit to add a preview of the page, boost results depending on where there are (title, keyword, ...), add stop words, etc. (Refer to the [Lunr docs](https://lunrjs.com/docs/index.html) for this as well as [the example repo](https://github.com/BLE-LTER/Lunr-Index-and-Search-for-Static-Sites) mentioned earlier or [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl/blob/master/assets/html/search.js)'s version).
+By default, the index built is fairly barebone to reduce the size of the generated index. If you want a fancier search, you might want to modify this a bit to add a preview of the page, boost results depending on where there are (title, keyword, ...), add stop words, etc. (Refer to the [Lunr docs](https://lunrjs.com/docs/index.html) for this as well as [the example repo](https://github.com/BLE-LTER/Lunr-Index-and-Search-for-Static-Sites) mentioned earlier or [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl/blob/master/assets/html/search.js)'s version).
\note{
Modify this file at will but be careful with the lines with `PATH_PREPEND` if your website is a project website (i.e. the root URL is something like `username.github.io/project/`). These lines help ensure that the generated links are valid. See also the section on [updating the index](#buildingupdating_the_index).
@@ -61,7 +61,7 @@ The file `lunrclient.js` (and its minified version) does the following:
- display the results
@@
-You might want to modify the `parseLunrResults` if you want the results to be displayed differently.
+You might want to modify the `parseLunrResults` if you want the results to be displayed differently.
\note{
If you modify this file, make sure it's called properly in the `_layout/index.html` and, eventually, [minify it](https://jscompress.com/).
@@ -115,7 +115,7 @@ Number of results found: ~~~~~~
~~~
```
-Note that if you modify the `id` of these elements, you will need to adapt the `lunrclient` file(s) accordingly.
+Note that if you modify the `id` of these elements, you will need to adapt the `lunrclient` file(s) accordingly.
## Building/updating the index
@@ -135,8 +135,8 @@ When you are ready to update your website you can either:
1. Call `lunr()` or `lunr(prepath)` if there is a prepath and then publish your updates manually.
@@
-The `publish(final=lunr)` calls the `lunr` function as a last step prior to doing a `git push`.
-An advantage of using this is that Franklin will properly handle the `prepath` if there is one defined in your `config.md`.
+The `publish(final=lunr)` calls the `lunr` function as the last step prior to doing a `git push`.
+An advantage of using this is that Franklin will properly handle the `prepath` if there is one defined in your `config.md`.
\note{
This `final=` keyword can be used with your own functions `()->nothing` if you need to do some post-processing with the generated files before pushing.
diff --git a/docs/extras/plotly.md b/docs/extras/plotly.md
index b9058495f..aee90581c 100644
--- a/docs/extras/plotly.md
+++ b/docs/extras/plotly.md
@@ -52,7 +52,7 @@ Finally, in your `src/_layout/head.html` add
## Offline-generated plot
-Assuming you already have the Plotly code for some plot, displaying the result on a page with Franklin is now pretty straightforward.
+Assuming you already have the Plotly code for some plot, displaying the result on a page with Franklin is now pretty straightforward.
Start by adding
```
@@ -91,7 +91,7 @@ This will give:
## Live-generated plot
-One step further is to use `PlotlyJS` to define a plot then pass the result to Franklin.
+One step further is to use `PlotlyJS` to define a plot and then pass the result to Franklin.
Start by adding `PlotlyJS` to your environment:
```julia-repl
@@ -141,9 +141,9 @@ fdplotly(json(plt)) # hide
\textoutput{ex1}
### Using `\fig{...}` (recommended)
-Now you might use `\fig{...}` to insert graph [just like normal](/syntax/markdown/#inserting_a_figure). This also work fine with `Plots.jl` and `PlotlyBase.jl`.
+Now you might use `\fig{...}` to insert graph [just like normal](/syntax/markdown/#inserting_a_figure). This also works fine with `Plots.jl` and `PlotlyBase.jl`.
-**Note**: `\fig{...}` will call the JavaScript function `PlotlyJS_json` defined [above](#pre-requisites). You might customize the behavior by modifying the JavaScript. Also make sure `@def hasplotly = true` is properly set.
+**Note**: `\fig{...}` will call the JavaScript function `PlotlyJS_json` defined [above](#pre-requisites). You might customize the behavior by modifying the JavaScript. Also, make sure `@def hasplotly = true` is properly set.
`````plaintext
```julia:ex2
diff --git a/docs/extras/utterances.md b/docs/extras/utterances.md
index 276793c40..b208a6d32 100644
--- a/docs/extras/utterances.md
+++ b/docs/extras/utterances.md
@@ -4,14 +4,14 @@
\toc\skipline
-Although Franklin generates static sites, you can add a commment widget to any webpage by using an external commenting system. There are several such systems, which work through some javascript or iframe code embedded in the page. The code works by calling an external server or app that handles the comment database and the interface with the user.
+Although Franklin generates static sites, you can add a comment widget to any webpage by using an external commenting system. There are several such systems, which work through some javascript or iframe code embedded in the page. The code works by calling an external server or app that handles the comment database and the interface with the user.
-We describe below how to implement a comment widget through [utterances](https://utteranc.es), which is a free, open-source, no-ads solution, which is pretty easy to set up. All the comments are saved in a github repository of your choosing, which can be the same repo that hosts the website or a different one. Each page that contains the javascript code for utterances is associated to an issue in the selected repository, and all the comments in that page are added as comments to that issue.
+We describe below how to implement a comment widget through [utterances](https://utteranc.es), which is a free, open-source, no-ads solution, which is pretty easy to set up. All the comments are saved in a Github repository of your choosing, which can be the same repo that hosts the website or a different one. Each page that contains the javascript code for utterances is associated with an issue in the selected repository, and all the comments on that page are added as comments to that issue.
-The comments in your page work just like comments in github issues, which means they have markdown rendering, code highlighting, and the basic github reaction emojis. Unfortunately, github's markdown does not render latex formulas, but they can be added by using an external renderer as described in [
-a-rodin/A hack for showing LaTeX formulas in GitHub markdown.md](https://gist.github.com/a-rodin/fef3f543412d6e1ec5b6cf55bf197d7b). It's not as friendly, but is doable. It is the same render used by github to display jupyter notebooks.
+The comments on your page work just like comments in github issues, which means they have markdown rendering, code highlighting, and the basic github reaction emojis. Unfortunately, github's markdown does not render latex formulas, but they can be added by using an external renderer as described in [
+a-rodin/A hack for showing LaTeX formulas in GitHub markdown.md](https://gist.github.com/a-rodin/fef3f543412d6e1ec5b6cf55bf197d7b). It's not as friendly but is doable. It is the same render used by Github to display jupyter notebooks.
-A notable thing missing from utterances is nested replies. Another drawback is that, since it is based on github issues, any user that wants to leave a comment has to have a github account and log in to proceed.
+A notable thing missing from utterances are nested replies. Another drawback is that, since it is based on Github issues, any user that wants to leave a comment has to have a Github account and log in to proceed.
If one is interested in trying other comment engines, here is a list of options, with some of them being paid and/or closed source: [Commento](https://commento.io), [GraphComment](https://graphcomment.com/en/), [IntenseDebate](https://intensedebate.com), [Isso](https://posativ.org/isso/), [Muut](https://muut.com), [Remark42](https://github.com/umputun/remark42), [StaticMan](https://staticman.net), and [Talkyard](https://www.talkyard.io).
@@ -21,23 +21,23 @@ The installation is pretty simple, and the [utterances](https://utteranc.es) pag
### Selecting the repository for storing the comments
-You need to choose a repository for storing the comments. It can be the same repository for the website, in case your site is hosted at github, or a different repository, if so you wish or need.
+You need to choose a repository for storing the comments. It can be the same repository for the website, in case your site is hosted on Github, or a different repository, if so you wish or need.
The selected page has to be public, so your commentators can write to it via utterances. In fact, utterances just provides the interface. The comment itself is owned by the user and can, in fact, also be written and accessed directly at the repo.
### Installing the utterances app
-There is an [utterances app](https://github.com/apps/utterances) that needs permission to access your github repo in order to write the comments. It is just a matter of clicking the `Configure` button that appears in the app's page and following the steps to select the right repository.
+There is an [utterances app](https://github.com/apps/utterances) that needs permission to access your Github repo in order to write the comments. It is just a matter of clicking the `Configure` button that appears on the app's page and following the steps to select the right repository.
### Configuring the javascript code
With the name of the repository at hand and the utterances app installed, it is time to configure the javascript code that is going to be inserted in the desired pages.
-There are a two required configurations to be made:
+There are two required configurations to be made:
@@tlist
-- *The blog post issue mapping*, which defines the form of the name to be given to the issue associated to each page containing the comment widget. There are a few options, as described in the [utterances](https://utteranc.es) page. The default is to have the title of the issue be the page pathname.
-- *The theme for the widget*. The default is "Github Light", but there a few others.
+- *The blog post issue mapping*, which defines the form of the name to be given to the issue associated with each page containing the comment widget. There are a few options, as described in the [utterances](https://utteranc.es) page. The default is to have the title of the issue be the page pathname.
+- *The theme for the widget*. The default is "Github Light", but there are a few others.
@@
And there is one optional configuration:
@@ -64,7 +64,7 @@ The *issue label* is optional, so it does not appear in the script above, but if
## Adding the comment widget
-With the javascript code ready, you need to add it to the desired page, be it a blog post or any other page. Of course you can just add the code above directly to an html file, or inject it to a markdown file by fencing it with `~~~...~~~`.
+With the javascript code ready, you need to add it to the desired page, be it a blog post or any other page. Of course, you can just add the code above directly to a html file, or inject it into a markdown file by fencing it with `~~~...~~~`.
But if you want to add it to several pages, as in posts for a blog, the best way is to add an `hfun_*` function to `utils.jl` and simply call this function at the end of each page.
@@ -97,7 +97,7 @@ Then, at the end of a markdown file, you just need to add
{{ addcomments }}
```
-With that done, each time someone leaves a comment in a page, the comment will be written to the repo, and you will receive an email from github telling you so.
+With that done, each time someone leaves a comment on a page, the comment will be written to the repo, and you will receive an email from Github telling you so.
## Working example
diff --git a/docs/faq/technical.md b/docs/faq/technical.md
index 9174d6db3..8a79deaf9 100644
--- a/docs/faq/technical.md
+++ b/docs/faq/technical.md
@@ -13,7 +13,7 @@ If you have a question that you couldn't find an answer to easily, don't hesitat
**Reference**: [issue 243](https://github.com/tlienart/Franklin.jl/issues/243), **more on this**: [styling](/styling/classes/).
-For the reference basically a footnote is inserted as
+For reference basically, a footnote is inserted as
```html
[1]
@@ -54,7 +54,7 @@ so you can style the back-reference via the `.franklin-content fndef td.fndef-ba
padding-left: 10px;}
```
-### How to disable numbering of math in display mode?
+### How to disable the numbering of math in display mode?
\note{This is currently only available when you're using KaTeX for maths.}
diff --git a/docs/faq/troubleshooting.md b/docs/faq/troubleshooting.md
index 6ab700aac..3c2cb7121 100644
--- a/docs/faq/troubleshooting.md
+++ b/docs/faq/troubleshooting.md
@@ -9,14 +9,14 @@ If you encounter an error that is not mentioned here, then it's probably a bug a
## Error on interruption
-You may (rarely) get an an error thrown at you when interrupting the server with `+C`, particularly when using Juno.
+You may (rarely) get an error thrown at you when interrupting the server with `+C`, particularly when using Juno.
There are a couple of reasons this may happen, both unrelated to Franklin.
### Juno
Juno (very rarely) crashes if you coincidentally press `+C` while Juno is doing something in the background (Juno issue [#309](https://github.com/JunoLab/Juno.jl/issues/309)).
-The stacktrace you will see will seem particularly obscure, for instance:
+The stack trace you will see will seem particularly obscure, for instance:
```
InterruptException:
@@ -43,7 +43,7 @@ Stacktrace:
The [`LiveServer.jl`](https://github.com/asprionj/LiveServer.jl) package, which handles the live-serving of the files, is based upon [`HTTP.jl`](https://github.com/asprionj/LiveServer.jl).
The latter has a fairly complex codebase with a number of asynchronous tasks and is known to sometimes crash in (somewhat) mysterious ways.
-If the stacktrace mentions `uv_write`, `uv_write_async`, `libuv` or something of the sorts, then this is an example of _known but mysterious way_.
+If the stack trace mentions `uv_write`, `uv_write_async`, `libuv` or something of the sort, then this is an example of _known but mysterious way_.
Like the "Juno" case, these errors are caused when you happen to press interrupt just as the package was doing something important in the background.
This is very rare but can happen and you can safely ignore it.
diff --git a/docs/faq/why-o-why.md b/docs/faq/why-o-why.md
index d9334b8b2..50d79d4e3 100644
--- a/docs/faq/why-o-why.md
+++ b/docs/faq/why-o-why.md
@@ -17,7 +17,7 @@ I liked that Jemdoc+Mathjax was simple to use and didn't require a lot of web-de
That's how I got the idea of doing something similar in Julia, hopefully improving on the few things I didn't like such as the lack of support for live-rendering preview or the speed of page generation.
That being said, if you just want a blogging generator mostly for text and pictures, then Franklin may not be the tool for you.
-If you want to host a technical blog with maths, code blocks, and would like some easy and reproducible control over elements, then Franklin could help you (feel free to [open an issue](https://github.com/tlienart/Franklin.jl/issues/new) to see if Franklin is right for you).
+If you want to host a technical blog with maths, an code blocks, and would like some easy and reproducible control over elements, then Franklin could help you (feel free to [open an issue](https://github.com/tlienart/Franklin.jl/issues/new) to see if Franklin is right for you).
### Why not Pandoc?
@@ -26,7 +26,7 @@ Franklin's aim was never to provide a full-fledged LaTeX to HTML conversion (whi
Rather, Franklin supports standard markdown **and** the definition of commands following a LaTeX-like syntax.
These commands can make the use of repeated elements in your website significantly easier to use and maintain.
-Further, Pandoc does not deal with the generation of a full website with things like live-previews, code evaluation etc.
+Further, Pandoc does not deal with the generation of a full website with things like live previews, code evaluation etc.
### Why write a markdown parser?
@@ -35,7 +35,7 @@ Franklin provided an incentive to think hard about how to parse extended markdow
In particular, processing LaTeX-like commands which can be re-defined and should be resolved recursively, proved pretty interesting (and sometimes a bit tricky).
-Initially Franklin was heavily reliant upon the Julia `Markdown` package (part of the `stdlib`) which can convert markdown to HTML but, over time, this changed as Franklin gained the capacity to parse a broader set of Markdown as well as extensions.
+Initially, Franklin was heavily reliant upon the Julia `Markdown` package (part of the `stdlib`) which can convert markdown to HTML but, over time, this changed as Franklin gained the capacity to parse a broader set of Markdown as well as extensions.
### Did you know?
@@ -49,4 +49,4 @@ After being kindly told that the name was awkward, I received great suggestions
- [Aretha Franklin](https://en.wikipedia.org/wiki/Aretha_Franklin), a great American singer.
@@
-There's also happens to be a turtle and a US president with that name but that's mostly fortuitous.
+There also happens to be a turtle and a US president with that name but that's mostly fortuitous.
diff --git a/docs/index.md b/docs/index.md
index d575a50d1..63aa0e2e7 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -48,7 +48,7 @@ julia> serve()
(use CTRL+C to shut down)
```
-If you navigate to that URL in your browser, you will see the website. If you then open `index.md` in an editor and modify it at will, the changes will be live rendered in your browser.
+If you navigate to that URL in your browser, you will see the website. If you then open `index.md` in an editor and modify it at will, the changes will be live rendered in your browser.
You can also inspect the file `menu1.md` which offers more examples of what Franklin can do.
## Installing optional extras
diff --git a/docs/styling/templates.md b/docs/styling/templates.md
index bf08b1903..4a2eb9d57 100644
--- a/docs/styling/templates.md
+++ b/docs/styling/templates.md
@@ -6,7 +6,7 @@ reviewed: 22/12/19
# Templates
-\blurb{Start from one of the template or build your own.}
+\blurb{Start from one of the templates or build your own.}
\lineskip
@@ -21,7 +21,7 @@ The pre-defined templates that are currently available in Franklin with the `new
\note{If you end up doing this, please consider making a PR to [FranklinTemplates](https://github.com/tlienart/FranklinTemplates.jl)!}
On this page, I'll take [Jemdoc's website layout](http://jemdoc.jaboc.net/) and show how it can be adapted to be a working Franklin template.
-This will hopefully also show you how to adapt / modify an existing template.
+This will hopefully also show you how to adapt/modify an existing template.
Jemdoc's layout looks like this:
@@ -35,7 +35,7 @@ In order to get a blueprint for the folder etc, let's first create a Franklin si
julia> newsite("jemdoc", template="basic")
```
-You can serve the site in order to see the modifications directly in your browser which can be useful to fine tune the port of the layout.
+You can serve the site in order to see the modifications directly in your browser which can be useful to fine-tune the port of the layout.
We will need to provide the appropriate stylesheet in `_css/` and adjust the layout part in `_layout/`.
@@ -60,9 +60,9 @@ The following step is fairly simple:
Let's do this gradually.
The top of the original HTML can be ignored at this point so we can start modifying starting after ``.
-Jemdoc's body starts with a Google analytics script which I'll ignore as well.
+Jemdoc's body starts with a Google Analytics script which I'll ignore as well.
We then have effectively one big table element.
-Stripped from its content and simplified it looks like:
+Stripped from its content and simplified it looks like this:
```html
@@ -87,7 +87,7 @@ Stripped from its content and simplified it looks like:
```
-Note that I've already filled in the `href=` in the links to sub-menus.
+Note that I've already filled in the `href=` in the links to the sub-menus.
The "`CONTENT HERE`" part is where what Franklin generates from Markdown will go.
Therefore, anything that is *after* that should go in `foot.html`; in our current case:
@@ -164,9 +164,9 @@ the content is not centred in its box and overflows on the right, the menu looks
Let's start by removing everything from `_css/jemdoc.css`.
Most of what's in there was used for the styling of the top navbar which we don't have anymore (note that the styling of the content itself is in `franklin.css`, don't change that for now; note also that `jemdoc.css` is loaded *after* `franklin.css` so that you can overwrite the styles there).
-Let's now just copy paste the content of the [two](http://jemdoc.jaboc.net/jemdoc.css) [original](http://jemdoc.jaboc.net/jacob.css) stylesheets into ours and hope for the best, we may have some fine-tuning to do after this.
+Let's now just copy-paste the content of the [two](http://jemdoc.jaboc.net/jemdoc.css) [original](http://jemdoc.jaboc.net/jacob.css) stylesheets into ours and hope for the best, we may have some fine-tuning to do after this.
-Doing nothing else than copy pasting already helps a lot:
+Doing nothing else than copy-pasting already helps a lot:
@@ -180,7 +180,7 @@ A few things should be fixed:
#### Fixing spacing
-Firefox or Chrome/ium's excellent dev-tools are super helpful to fine tune stylesheets.
+Firefox or Chrome/ium's excellent dev-tools are super helpful to fine-tune stylesheets.
Here things are pretty straightforward though.
First, we need to add vertical padding above `` level title:
@@ -215,7 +215,7 @@ pre {
which you can just remove to have a bit more space around code blocks.
-There's probably still things that could be done to improve the layout overall (and make it more responsive!) but we'll leave it at that.
+There are probably still things that could be done to improve the layout overall (and make it more responsive!) but we'll leave it at that.
@@ -242,6 +242,6 @@ It should be fairly straightforward to adapt that to your needs.
## Making a PR to the theme repo
-Let's say you've built your own template and are pretty happy with the result and you'd like to share it for other users, great, thanks!
+Let's say you've built your own template and are pretty happy with the result and you'd like to share it with other users, great, thanks!
Please follow [these instructions](https://github.com/tlienart/FranklinTemplates.jl#fixingadding-a-template).
diff --git a/docs/syntax/divs-commands.md b/docs/syntax/divs-commands.md
index 96bd5ba16..17cae606a 100644
--- a/docs/syntax/divs-commands.md
+++ b/docs/syntax/divs-commands.md
@@ -67,7 +67,7 @@ The distinction with inserting raw HTML div blocks with the `~~~...~~~` syntax i
## LaTeX-like commands
Franklin allows the definition of commands using a LaTeX-like syntax.
-This can be particularly useful for repeating elements or styling inside or outside of maths environment.
+This can be particularly useful for repeating elements or styling inside or outside of the maths environment.
To define a command, you **must** use the following syntax:
@@ -113,7 +113,7 @@ $$ \mathcal W_\psi[f] = \int_\R f(s)\psi(s)\mathrm{d}s = \scal{f,\psi} $$
### Text examples
-Commands can also be useful outside of maths environment.
+Commands can also be useful outside of the maths environment.
For instance, you could define a command to quickly set the style of some text:
```html
@@ -200,7 +200,7 @@ and specify the styling of the `definition` div in your CSS:
In a Franklin `newcommand`, to refer to an argument you can use `#k` or `!#k`.
There is a small difference: the first one _introduces a space_ left of the argument while the second one does not.
-In general whitespaces are irrelevant and will not show up on the rendered webpage so that the usual `#k` is the recommended usage.
+In general, whitespaces are irrelevant and will not show up on the rendered webpage so the usual `#k` is the recommended usage.
This helps avoid some ambiguities when resolving a chain of nested commands.
There are however cases where you do not want this because the whitespace does, in fact, show up.
@@ -222,7 +222,7 @@ Here \pathwith{hello} is no good whereas \pathwithout{hello} is.
### Defining commands globally
-If you define commands on a page, the command will be available only on that page; if you wish to define a command that is available on all pages, you should put the definition of the command in your `config.md` file.
+If you define commands on a page, the command will be available only on that page; if you wish to define a command that is available on all pages, you should put the definition of the command in your `config.md` file.
## Hyper-references
@@ -231,7 +231,7 @@ Three types of hyper-references are supported in Franklin:
@@flist
1. for equations in display mode,
1. for references (bibliography),
-1. for specific anchor points in the page.
+1. for specific anchor points on the page.
@@
The syntax for all three is close to that of standard LaTeX.
@@ -262,13 +262,13 @@ As in LaTeX, you can refer to several equations in one shot by separating names
For references, you can use `\biblabel{short}{name}` to declare a reference which will appear as a clickable link `(name)` or `name` and can be referred to with `short`:
```plaintext
-In the text you may refer to \citep{noether15, bezanson17} while in a bibliography section you would have
+In the text, you may refer to \citep{noether15, bezanson17} while in a bibliography section you would have
* \biblabel{noether15}{Noether (1915)} **Noether**, Korper und Systeme rationaler Funktionen, 1915.
* \biblabel{bezanson17}{Bezanson et al. (2017)} **Bezanson**, **Edelman**, **Karpinski** and **Shah**, [Julia: a fresh approach to numerical computing](https://julialang.org/publications/julia-fresh-approach-BEKS.pdf), SIAM review 2017.
```
-The `name` argument therefore corresponds to how the bibliography reference will appear in the text.
+The `name` argument, therefore, corresponds to how the bibliography reference will appear in the text.
In the case above, the text will lead to
```plaintext
@@ -286,7 +286,7 @@ As in LaTeX, if the reference is undefined on the page, the command will be repl
### Anchor points
-You can specify anchor points on the page using `\label{name of the anchor}` anywhere on the page _outside_ of maths environment.
+You can specify anchor points on the page using `\label{name of the anchor}` anywhere on the page _outside_ of the maths environment.
This will insert an anchor:
```html
diff --git a/docs/syntax/markdown.md b/docs/syntax/markdown.md
index fbe19ee36..b93a3b300 100644
--- a/docs/syntax/markdown.md
+++ b/docs/syntax/markdown.md
@@ -94,7 +94,7 @@ reference: ![alt text][ref]
### Lists
-Un-ordered list (you can also use `-`, `+` or `.` instead of `*`)
+Unordered list (you can also use `-`, `+` or `.` instead of `*`)
```markdown
* item 1
@@ -114,7 +114,7 @@ Ordered list (the proper numbering is done automatically)
### Comments
-You can add comments in your markdown using HTML-style comments: `` possibly on multiple lines. Note that comments are **not** allowed in a math environment.
+You can add comments in your markdown using HTML-style comments: `` possibly on multiple lines. Note that comments are **not** allowed in a math environment.
### Symbols and HTML entities
@@ -154,7 +154,7 @@ println(a)
You're not obliged to specify the language, if you don't it will assume the language corresponds to the [page variable](/syntax/page-variables/) `lang` (set to `julia` by default).
If you want the block to be considered as plaintext, use `plaintext` as the language specifier.
-Finally you can also use indented code blocks (which will also take its highlighting hint from `lang`) but this is **not recommended** and you have to explicitly opt-in by setting `indented_code` on a page that would use them:
+Finally, you can also use indented code blocks (which will also take its highlighting hint from `lang`) but this is **not recommended** and you have to explicitly opt in by setting `indented_code` on a page that would use them:
```markdown
@def indented_code = true
@@ -182,7 +182,7 @@ this will not be highlighted
```
`````
-If you wish to have higlighting for more languages outside of the pre-rendering mode, head to [highlight.js](https://highlightjs.org/), make a selection of languages and place the resulting `higlight.pack.js` in the `/_libs/highlight/` folder.
+If you wish to have highlighting for more languages outside of the pre-rendering mode, head to [highlight.js](https://highlightjs.org/), make a selection of languages and place the resulting `highlight.pack.js` in the `/_libs/highlight/` folder.
If you do this, you might want to slightly modify it to ensure that the Julia-repl mode is properly highlighted (e.g. `shell>`):
@@tlist
@@ -198,7 +198,7 @@ hljs.registerLanguage("julia-repl",function(a){return{c:[{cN:"meta",b:/^julia>/,
### Evaluated code blocks
-Julia code blocks can be evaluated and the result of the code either shown or rendered.
+Julia code blocks can be evaluated and the result of the code is either shown or rendered.
To declare a code block for evaluation, use the fenced code block syntax with a name for the code block:
`````markdown
@@ -241,9 +241,9 @@ Inline: $x=5$ or display:
$$ \mathcal W_\psi[f] = \int_{\mathbb R} f(s)\psi(s)\mathrm{d}s $$
-You can also use `\[...\]` for display maths.
+You can also use `\[...\]` for display maths.
-One thing to keep in mind when adding maths on your page is that you should be generous in your use of whitespace, particularly around inequality operators to avoid ambiguity that could confuse KaTeX.
+One thing to keep in mind when adding maths on your page is that you should be generous in your use of whitespace, particularly around inequality operators to avoid the ambiguity that could confuse KaTeX.
So for instance prefer: `$0 < C$` to `$0
```
-which could be useful as footer on all pages.
+which could be useful as a footer on all pages.
-The syntax `{{ ... }}` indicates a HTML _function_, `fill` is the function name and the rest of the bracket elements are _page variables_ (here `author`) serving as arguments of the function.
+The syntax `{{ ... }}` indicates an HTML _function_, `fill` is the function name and the rest of the bracket elements are _page variables_ (here `author`) serving as arguments of the function.
\note{
- Calls without arguments such as `{{ name }}` will be interpreted in either one of two way: first it will check whether there is a html function `name` and if so will call it, otherwise it will check whether there is a page variable `name` and will just insert it -- it will be treated as a shortcut for `{{fill name}}`.
+ Calls without arguments such as `{{ name }}` will be interpreted in either one of two ways: first, it will check whether there is am html function `name` and if so will call it, otherwise it will check whether there is a page variable `name` and will just insert it -- it will be treated as a shortcut for `{{fill name}}`.
}
### Local and Global
_Local_ page variables denote variables that are defined on one page and directly accessible on that page. _Global_ page variables, by contrast, are directly available on _all_ pages. Any variable defined in your `config.md` file is global.
-In both cases there are _default_ page variables set by Franklin with default values which you can both change and use.
+In both cases, there are _default_ page variables set by Franklin with default values which you can both change and use.
You can of course also define your own variables, both global and local.
### Defining and accessing page variables
@@ -143,7 +143,7 @@ the conditional blocks are explained below.
### Conditional blocks
-Conditional blocks allow to specify which parts of the HTML template should be active depending on the value of given page variable(s).
+Conditional blocks allow specifying which parts of the HTML template should be active depending on the value of the given page variable(s).
The format follows this structure:
```html
@@ -259,7 +259,7 @@ Remember that:
- you can also define your own variables (with different names),
- you can change the default value of a variable by defining it in your `config.md`.
@@
-Note that variables shown below that have a name starting with `fd_` are _not meant to be defined_ as their value is typically computed on the fly (but they can be used).
+Note that variables shown below that have a name starting with `fd_` are _not meant to be defined_ as their value is typically computed on the fly (but they can be used).
### Basic settings
@@ -283,12 +283,12 @@ Note that variables shown below that have a name starting with `fd_` are _not
**Notes**:\\
\smindent{(\*)} \smnote{if the title is not set, the first header will be used as title}.\\
-\smindent{(\*\*)} \smnote{there may be cases where you want to literally type `]:` in some code without it indicating a link reference. In such case, set `reflinks` to `false` to avoid ambiguities}.\\
+\smindent{(\*\*)} \smnote{there may be cases where you want to literally type `]:` in some code without it indicating a link reference. In such a case, set `reflinks` to `false` to avoid ambiguities}.\\
\smindent{(\*\*\*)} \smnote{it is recommended to fence your code blocks (use backticks) as it's not ambiguous for the parser whereas indented blocks can be. If you do want to use indented blocks as code blocks, it's your responsibility to make sure there are no ambiguities}.
### Code evaluation
-For more informations on these, see the section on [inserting and evaluating code](/code/).
+For more information on these, see the section on [inserting and evaluating code](/code/).
@@lalign
| Name | Type | Default value | Comment
diff --git a/docs/syntax/rss.md b/docs/syntax/rss.md
index 69848d6f4..a88814384 100644
--- a/docs/syntax/rss.md
+++ b/docs/syntax/rss.md
@@ -20,7 +20,7 @@ this feed so that readers can more easily stay up to date with your new content.
## How to Setup RSS
-There is a Franklin generated `_rss` folder that contains two parts: `head.xml`
+There is a Franklin-generated `_rss` folder that contains two parts: `head.xml`
& `item.xml` (if this is not present for you, then copy the files from the
[FranklinTemplates source](https://github.com/tlienart/FranklinTemplates.jl/tree/master/src/templates/common/_rss).
@@ -40,7 +40,7 @@ standards. However, their contents may be modified.}
### Global Configuration
-In order to setup an RSS feed for your website, make sure to set the following
+In order to set up an RSS feed for your website, make sure to set the following
in your `config.md`.
```julia
@@ -89,7 +89,7 @@ Optionally, the following page variables can be set as well
- `rss_enclosure`
\warn{Check the RSS specifications before using these optional page variables as
-many have strict requirements and should probably be left blank. For instance
+many have strict requirements and should probably be left blank. For instance,
the `rss_author` variable **must** be an email address. So unless you are
familiar it is advised to leave these out.}
diff --git a/docs/syntax/utils.md b/docs/syntax/utils.md
index 850f7c619..aff5c7e29 100644
--- a/docs/syntax/utils.md
+++ b/docs/syntax/utils.md
@@ -11,7 +11,7 @@ These functions are to be defined in the `utils.jl` file which lies at the same
They **must** be named with `lx_` or `hfun_` followed by a name; for instance: `lx_foo`, `hfun_bar_baz` are accepted.
These functions are defined in plain Julia and can themselves call other functions that would be defined in the `utils.jl` file or elsewhere.
-**Note**: often, it is enough to use `~~~...~~~` blocks or define newcommands (or both) rather than use `hfun_*` and `lx_*`; but sometimes it can be very convenient to have a way to just generate things with your own code.
+**Note**: often, it is enough to use `~~~...~~~` blocks or define `newcommand`s (or both) rather than use `hfun_*` and `lx_*`; but sometimes it can be very convenient to have a way to just generate things with your own code.
For instance, to locally use custom styling of text, Franklin comes with the following command:
```html
@@ -74,7 +74,7 @@ You can also have parameters with `hfun_*` functions which will allow you to wri
the parameters are passed as a **vector of strings** i.e.: in the case above, the function will receive `["arg1", "arg2"]` and these strings will need to be further processed by the function.
-The procedure is otherwise the same than at the previous point, you just need to define the function like this:
+The procedure is otherwise the same as at the previous point, you just need to define the function like this:
```julia
function hfun_bar(params)
@@ -90,7 +90,7 @@ Note that all functions defined in `utils.jl` can call `locvar(name)` and `globv
A `lx_*` function is a way to bypass Franklin's parsing and generate Markdown which will be _reprocessed_ by Franklin (though you can always avoid that by generating HTML directly after wrapping it in `~~~`).
-This is a more advanced command and you should probably double check before making use of it as, usually, there will be a simpler way of achieving what you want.
+This is a more advanced command and you should probably double-check before making use of it as, usually, there will be a simpler way of achieving what you want.
Also if you intend to use it, you will want to check out [FranklinUtils](http://github.com/tlienart/FranklinUtils.jl) which provides helper functions for it.
It's harder to come up with meaningful examples as most simple examples will be achievable another way so here we proceed with a dumb example (and will show why it's dumb later).
@@ -120,13 +120,13 @@ function lx_h2(com, _) # the signature must look like this
end
}
-\note{Same comment as earlier, you can see that the way the function is called depends on the name of the function definition `lx_foo` ⟶ `foo`. Make sure that the name does not clash with one of the pre-defined commands (`label`, `style`, ...).}
+\note{The same comment as earlier, you can see that the way the function is called depends on the name of the function definition `lx_foo` ⟶ `foo`. Make sure that the name does not clash with one of the pre-defined commands (`label`, `style`, ...).}
\note{For the moment, this only works with a single brace see [issue 518](https://github.com/tlienart/Franklin.jl/issues/518) for comments.}
### Why it was a dumb example
-In this case it would have been simpler to just define this as a simple newcommand:
+In this case, it would have been simpler to just define this as a simple newcommand:
```html
\newcommand{\h2}[2]{~~~#2
~~~}
diff --git a/docs/workflow/deploy.md b/docs/workflow/deploy.md
index 4883fca3d..153742c3d 100644
--- a/docs/workflow/deploy.md
+++ b/docs/workflow/deploy.md
@@ -12,9 +12,9 @@ reviewed: 18/10/20
\lineskip
-Deploying the website is trivial on an existing webserver, via GitHub or Gitlab, or on services like Netlify.
+Deploying the website is trivial on an existing web server, via GitHub or Gitlab, or on services like Netlify.
-## Deploying on an existing webserver
+## Deploying on an existing web server
The contents of the `__site` folder can simply be deployed to a path on an existing server as follows.
Supposing you wish your site to appear at `http://my.example.com/path/to/my/franklin/site/`. You would take the following steps:
@@ -33,7 +33,7 @@ Your site should now be live, with the index page appearing at `http://my.exampl
Start by creating an empty GitHub repository
@@tlist
-* for a personal (or org) website the repository **must** be named `username.github.io` (or `orgname.github.io`) see also [the github pages docs](https://pages.github.com/),
+* for a personal (or org) website the repository **must** be named `username.github.io` (or `orgname.github.io`) see also [the Github pages docs](https://pages.github.com/),
* for a project website the repo can be named anything you want, let's say `myWebsite`.
@@
@@ -42,7 +42,7 @@ Start by creating an empty GitHub repository
This is used upon deployment to indicate that the base URL of your website is `username.github.io/myWebsite/` instead of `username.github.io`.
If you forget to do that, among other problems the CSS won't load and your website will look terrible 😅.
- However, if you add a custom domain like `example.com` to your *project* repo like `myWebsite`, then the variable `prepath` should be set empty string to make the CSS work.
+ However, if you add a custom domain like `example.com` to your *project* repo like `myWebsite`, then the variable `prepath` should be set an empty string to make the CSS work.
}
@@tlist
@@ -60,7 +60,7 @@ You now just need to synchronise your repository and your local website folder;
- `git push`
@@
-the GitHub action will be triggered and deploy the content of the `__site` folder to the `gh-pages` branch from which GitHub will deploy the website.
+the GitHub action will be triggered and deploy the content of the `__site` folder to the `gh-pages` branch from which GitHub will deploy the website.
\note{It takes a couple of minutes for the whole process to complete.}
@@ -113,7 +113,7 @@ If something failed, that you can't debug, ask on the **#franklin** slack channe
Start by creating an empty GitLab repository
@@tlist
-* for a personal website the repository **must** be named `username.gitlab.io` see also [the gitlab pages docs](https://about.gitlab.com/stages-devops-lifecycle/pages/),
+* for a personal website the repository **must** be named `username.gitlab.io` see also [the Gitlab pages docs](https://about.gitlab.com/stages-devops-lifecycle/pages/),
* for a project website the repo can be named anything you want.
@@
@@ -136,7 +136,7 @@ That's it! when you push your updates to the `master` branch, the GitLab CI will
### Iterate
-The `publish` command does the optimize followed by the git stuff all in one. So you should probably use that after the initial setup.
+The `publish` command does the optimize followed by the git stuff all in one. So you should probably use that after the initial setup.
## Deploying on Netlify
@@ -184,7 +184,7 @@ where `{netlify name}` is a name you will decide to use at the end of this expla
The first line keeps track of the URL where the preview will be available.
the second line only keeps track of the "prepath" of that preview URL so that it can be passed to Franklin.
-Finally we want to deploy the main website and the PR preview on different branches (and folders):
+Finally, we want to deploy the main website and the PR preview on different branches (and folders):
```yml
- name: Deploy (preview)
if: github.event_name == 'pull_request' && github.repository == github.event.pull_request.head.repo.full_name # if this build is a PR build and the PR is NOT from a fork
@@ -218,9 +218,9 @@ to
Now for the final step, you will need to visualize the obtained previews.
Since Github only allow you to deploy one branch, you will need an alternative like Netlify.
Create an account on [Netlify.com](https://www.netlify.com/), add your repository and chose the `gh-preview` branch without any additional settings.
-Set your netlify website to be `{netlify name}.netlify.app`.
+Set your Netlify website to be `{netlify name}.netlify.app`.
-Once everything is setup you will be able to visualize your PR preview on `{netlify name}.netlify.app/previews/PR{number of your PR}`.
+Once everything is set up you will be able to visualize your PR preview on `{netlify name}.netlify.app/previews/PR{number of your PR}`.
You can make things easier for your contributors to access it by adding a comment with a link to your PR automatically.
To do this add the following Github action (create a `pr_comment.yml` file in `.github/workflows/`):
```yml
diff --git a/docs/workflow/index.md b/docs/workflow/index.md
index 553a7b365..80c0ab572 100644
--- a/docs/workflow/index.md
+++ b/docs/workflow/index.md
@@ -26,7 +26,7 @@ There are a number of [simple templates](https://tlienart.github.io/FranklinTemp
\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
+Once you have created a new website folder, you can start the live rendering of your website with
```julia-repl
julia> serve()
@@ -71,17 +71,17 @@ 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.
+* `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 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{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 in 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:
+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
+So for instance, if we ignore auxiliary files and you have
```
.
@@ -103,7 +103,7 @@ __site
└── index.html
```
-which allows to have the following URLs:
+which allows having the following URLs:
@@tlist
* `[website]/`
@@ -113,7 +113,7 @@ which allows to have the following URLs:
### Reserved names
-To avoid name clashes, refrain from using the following paths where `/` indicates the topdir (website folder):
+To avoid name clashes, refrain from using the following paths where `/` indicates the top directory (website folder):
@@tlist
* `/css/` or `/css.md`
@@ -130,7 +130,7 @@ All pages with a given tag can be found (by default) at `[website]/tag/ verify_links()
@@ -162,7 +162,7 @@ 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 as [broken-link-checker](https://github.com/stevenvachon/broken-link-checker#readme).
+ 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 as [broken-link-checker](https://github.com/stevenvachon/broken-link-checker#readme).
}
### Pre-rendering and compression
@@ -179,7 +179,7 @@ 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).
\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 with `optimize(minify=false)`.
+ 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 with `optimize(minify=false)`.
Also note that if you use GitHub or GitLab pages, the minification is not needed as these platforms compress the pages themselves.
}
@@ -191,7 +191,7 @@ Note that in order to run them, you will need a couple of external dependencies
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),
+- applies an optional optimisation step (see the previous point),
- does a `git add -A; git commit -am "franklin-update"; git push`.
@@
diff --git a/docs/workflow/structure.md b/docs/workflow/structure.md
index af45525e1..ba6d9ca40 100644
--- a/docs/workflow/structure.md
+++ b/docs/workflow/structure.md
@@ -48,7 +48,7 @@ The final HTML for a page will essentially look like: