Skip to content

Latest commit

 

History

History
170 lines (124 loc) · 6.81 KB

website-admin-instructions.md

File metadata and controls

170 lines (124 loc) · 6.81 KB
Raw

website-memo

This document lists the basics on how to edit the course website accessible at https://gridap.github.io/GridapWorkshopNCI2023.

Franklin static website

To test the website locally (or after making a pull from Git):

julia> using Franklin, NodeJS

julia> serve(clear=true)

Note the first time you are using NodeJS, you need to execute:

julia> run(`sudo $(npm_cmd()) install highlight.js`)

How-to

Add YouTube video

To embed YouTube videos, go to YouTube, click on the Share link and then <Embed>, and copy-paste the script into an html block:

~~~
<iframe width="560" height="315" src="https://www.youtube.com/embed/DvlM0w6lYEY" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
~~~

Notebook, code, and markdown with Franklin

Using Literate.jl permit to write a single .jl source file that can contain Julia code and markdown comments and can be transformed into a markdown page, a notebook and notebook-based slides. The website build with Franklin.jl has native support to integrate .jl scripts ready to be processed by Literate.jl in markdown.

To allow mdstring to render correctly in Franklin, one need to set the page variable literate_mds = true. See here for details.

To disable code execution but allow rendering on the website, one needs to set the page variable noeval = true. See here for details.

Display Julia script as Markdown page on the website

  1. Create a Literate-ready my_script.jl script

  2. Place it in the _literate folder

  3. Add \literate{/_literate/my_script.jl} in the website page you want to include my_script.jl markdown rendering

  4. Done

Note that there are 2 pre-defined box environments to highlight note and warning. Use them as following:

#md # \note{...}
#md # \warn{...}

Notebook deploy

Running the deploy_notebooks.jl scripts located in slide-notebooks and exercise-notebooks folder will:

  • create .ipynb from the .jl script
  • move the .ipynb and figures to the ./notebook folder (and ./notebook/figures)
  • create a _web.jl script and move it to website/_literate to be included in the website lecture pages. Figure links in the _web.jl files are changes from ./figures/ to ../website/_assets/literate_figures/ for correct rendering in html file.
  • create, if needed, a figures folder in website/_assets/literate_figures folder to hold figures for Literate scripts
  • 💡 both deploy script contain a variable incl::String you can set to only include specific scripts (e.g. incl=l2, incl=lecture2)

Important note: The deploy_notebooks.jl script in slide-notebooks makes it possible to preprocess the Literate script for hints and solution keywords:

## Set `sol=true` to produce output with solutions contained and hints stripts. Otherwise the other way around.
sol = true

You can populate lines beginning of Literate script with #hint= or #sol= which will permit to corresponding lines to be removed upon preprocessing (e.g. before / after the lecture).

To deploy notebooks

  1. Run the deploy script from its folder
  2. Include the correct _web.jl filename in e.g. website/lectureXY.md file
  3. Push

Launch a notebook from the script

  1. In Julia, load Literate and export my_script.jl as a notebook:
julia> using Literate

julia> Literate.notebook("my_script.jl", outputdir=pwd())
  1. Then load IJulia and launch the notebook for the given path
julia> using IJulia

julia> notebook(dir="/some/path")

Transform the notebook into a presentation

  1. To allow for slide rendering as slide, subslide or fragment, populate my_script.jl "source" code with
#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide/subslide/fragment"}}

  1. To view the notebook as a slideshow, install the RISE plugin.

  2. Open the notebook as in here

  3. Press alt-r to start. Use spacebar to advance.

Generate mp4 out of gif

In the second edition, we prefer mp4 instead of gif. Using FFMPEG, one can swiftly convert gifs into mp4:

run(`ffmpeg -i input_anim.gif -c libx264 -pix_fmt yuv420p -vf "pad=ceil(iw/2)*2:ceil(ih/2)*2:color=white" -y output_anim.mp4`)

Or generate them from pngs:

run(`ffmpeg -framerate 30 -i %%04d.png -c libx264 -pix_fmt yuv420p -vf "pad=ceil(iw/2)*2:ceil(ih/2)*2:color=white" -y output_anim.mp4`)

The mp4 animation can then be embedded as follow in Literate.jl scripts:

#md # ~~~
# <center>
#   <video width="80%" autoplay loop controls src="./path-to-anim/anim.mp4"/>
# </center>
#md # ~~~

or directly into .md scripts as

<center>
  <video width="80%" autoplay loop controls src="./path-to-anim/anim.mp4"/>
</center>

gif and loopcount

You can use gifsicle as command line tool to modify the loopcount for gifs to be included in the scripts (tested on MacOS):

gifsicle gif_loopcount_inf.gif --no-loopcount > new_gif_no_loopcount.gif
gifsicle gif_loopcount_inf.gif --loop=3 > new_gif_loopcount_3.gif

Misc

Control the global page content width

Put in _layout/head the following, before the opening of the body and after the loading of the css:

<style>
.content {max-width: 50rem}
</style>

HTML color-picker

https://www.w3schools.com/colors/colors_picker.asp

Additional notes

The scripts have been moved to GridapWorkshop2023Material, which is listed in this repo as a submodule in workshop-materials. This allows for the following:

  • The fully-annotated scripts are in workshop-materials/src. These scripts can be processed to generate the different tutorial formats.
  • The script workshop-materials/src/_build.jl parses the scripts and generates
    • a jupyter notebook version in workshop-materials/notebooks.
    • a stripped script version in workshop-materials/scripts.
  • The script process_materials.jl parses the scripts and generates the .jl files in the folder _literate, which can then be included by Franklin.jl.

Changes pushed to the submodule will not be seen by this repository (since the submodule is pinned to a specific commit). To update the submodule, do the following:

git submodule update --remote
git add workshop-materials
git commit -m "git submodule updated"
git push origin main

Alternatively, one can work locally from this repo, doing changes to both repositories then commiting and pushing the changes to both repos.