PkgPage.jl

About this Package

PkgPage uses Bootstrap 4.5 and is meant to be particularly easy to use with minimal need to tweak HTML or CSS to get a great-looking result. With it you can:

• easily insert and style figures and tables,

• easily initiate a multi-columns environment,

• easily control the layout, colors, code theme etc from the config file,

• automatic insertion of new sections into the navbar,

• automatic purging of bootstrap css to remove unused rules,

• all the goodies from Franklin.jl:

  • live-rendering,

  • support for KaTeX and highlight.js and automatic pre-rendering,

  • and much more.

Commands

• Sections

• Figures

• Tables

• Columns

• Maths

• Misc

Sections: you can indicate a section as follows:

\begin{section}{opts...}
text
\end{section}

where the available options are:

• title="..." to add a heading to the section, this should be provided,

• name="..." to add a specific name that will appear in the navbar (if not given, it will use the given title).

• width=8 an integer number controlling the width of the section with respect to the body, increase it to get a wider section.

Figures: you can indicate a figure as follows:

\figure{path="...", opts...}

where path is a valid path to the image (e.g. /assets/image.png) and the other available options are:

• width="..." to specify the width of the image (e.g. 100%),

• alt="..." to specify the image alt,

• caption="..." to specify the figure caption if any,

• style="..." to add any specific CSS styling to the image (e.g. border-radius:5px).

Note: alt and caption are passed as HTML strings so, for instance, if you want a line break you will need to use <br> or if you want maths in the caption you will need to put it between escaped brackets \(x^2\sin(\mu)\) instead of $.

$x^2\sin(\mu)$)." class="figure-img img-fluid " width="100%" style="border-radius:5px;">

Tables: you can insert a table as follows:

\begin{table}{opts...}
| Column One | Column Two | Column Three |
|----------: | ---------- |:------------:|
| Row `1`    | Column `2` |              |
| *Row* 2    | **Row** 2  | Column ``3`` |
\end{table}

where the available options are:

• caption="...": to add a caption to the table,

• class="...": to add specific bootstrap classes to the table (e.g. table-striped),

• style="...": for any further styling.

Columns: you can declare an environment with columns with:

\begin{columns}
\begin{column}{}
...
\end{column}
\begin{column}{}
...
\end{column}
\end{columns}

For instance you can use this to produce:

Maths

Just use $$ ... $$ for display math and $ ... $ for inline maths:

where $P_n$ is the $n$-th Legendre polynomial and $x_i$ is it's $i$-th root.

Misc

• you can use \\ to add some vertical space (skip a line)

• you can use \begin{center}...\end{center} to center some content

• you can use \style{css}{content} to get css-styled text for instance \style{color:red;text-transform:uppercase;}{hello} gives hello

• you can use \alert{...} to draw attention to some text via a coloured box.

You can also define your own commands which can be as complex as you might want, see the Franklin docs for more information.

Deployment

By following these instructions, the content of the rendered website will be copied to a gh-pages branch where it will be deployed by GitHub. If you would like to deploy the page with your own URL or using something else than GitHub, have a look at the specific instructions further on.

Adjust DeployPage: start by checking the .github/workflows/DeployPage.yml in particular:

• if you want to use Python or matplotlib, uncomment the relevant lines

• in the run block ensure that

  • NodeJS and PkgPage are added,

  • any packages that your page might rely on are added,

  • the optimize call has the appropriate input and output path (if you're in the default setting, leave as is).

GitIgnore: it's important you specify that page/__site should be ignored by git and not pushed to your repository otherwise the build process might not work properly. To do so create a file .gitignore containing the line

page/__site

as shown here.

GitAttributes: in order for GitHub to ignore page folder it the language statistics for your repository, make sure to add a file .gitattributes with content

page/* linguist-vendored

like this.

Now whenever you push changes to the master branch of your package, the build process will be triggered and your page updated and deployed. That's it.

Avoiding clashes with Documenter.jl: if you already use Documenter.jl you might want your page to be deployed in a specific folder of gh-pages as Documenter also generates files in gh-pages.

you can do so in two steps:

1. change the run part of DeployPage.yml by specifying the output keyword argument in PkgPage.optimize for instance: PkgPage.optimize(input="page", output="page"),

2. change the prepath in config.md to reflect that the base URL will contain that additional folder, for instance @def prepath = "YourPackage.jl/page".

Use your own URL: you can usually get host services like Netlify to deploy a specific branch of a GitHub repo, do make sure to set @def prepath = "" in your config.md though.

If you want to do the deployment without GitHub actions then you will need to:

• ensure you have purgecss and highlights installed and available to NodeJS, the simplest way to do this is to install them via NodeJS with

using NodeJS;
run(`$(npm_cmd()) install highlight.js`);
run(`$(npm_cmd()) install purgecss`);

• run PkgPage.optimize(input="page", output="") (adapting input as required)

• place the content of page/__site wherever your server requires it.