Static websites

Static websites#

When: Tuesday 23 January 2024
Presenters: Alexandre Boucaud and Maude Le Jeune

Markdown syntax#

Markdown is a lightweight markup language that allows you to format text in a simple and readable way. Here are some basic syntax elements:

Headers#

Use the # symbol to create different levels of headers. For example:

  • # Header 1 creates a top-level header

  • ## Header 2 creates a second-level header

  • ### Header 3 creates a third-level header

Emphasis#

Use the * or _ symbols to emphasize text. For example:

  • *italic* or _italic_ creates italic text

  • **bold** or __bold__ creates bold text

Lists#

Use - or * for unordered lists, and 1. for ordered lists. For example:

  • - Item 1 creates an unordered list item

  • * Item 2 also creates an unordered list item

  • 1. Item A creates an ordered list item

Images#

Use ![alt text](image url) to insert an image. For example:

  • ![Logo](https://example.com/logo.png) inserts an image with alt text “Logo”

Code#

Use `code` to highlight inline code and ```code``` for code blocks. For example:

  • `print(“Hello, World!”)` highlights inline code

  • ```python\ncode block\n``` creates a code block

Jupyter-book#

Jupyter Books is an open-source project that allows you to create interactive and dynamic publications from Jupyter Notebooks. It uses the R Markdown, MyST, or Markdown formats, and enables you to easily combine code, narrative text, visualizations, and other multimedia content into a single publication. The project is built on top of Jupyter Notebooks and utilizes Jupyter’s rich display capabilities to create interactive web-based books that are easy to author and share with others.

Key features of Jupyter Books include:

  1. Interactive content: You can embed live, interactive code snippets within your book, allowing readers to run the code themselves right in their browser.

  2. Rich media support: Jupyter Books supports a wide range of multimedia content, including images, videos, and interactive widgets.

  3. Automatic conversion: Jupyter Books can automatically convert Jupyter Notebooks into HTML, PDF, or ePub formats for easy distribution and sharing.

  4. Customizable themes: You can customize the appearance of your book by applying different CSS stylesheets or using pre-built templates.

  5. Community support: As an open-source project, Jupyter Books benefits from a growing community of contributors who actively develop new features and improvements.

To get started with Jupyter Books, you can check out the official documentation at https://jupyterbook.org/.

Example website

This very website is built with Jupyter Books. Have a look at the source code here: https://gitlab.in2p3.fr/si-apc/cafe-info

MkDocs#

MkDocs is a fast, simple, and downright stunning static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file, which helps to keep things simple. MkDocs is a Python-based application, so you can install it using pip, the standard package manager for Python.

Key features of MkDocs include:

  1. Easy setup and use - MkDocs aims to make creating project documentation as easy as possible, with minimal setup required.

  2. Markdown content - Documentation source files are written in Markdown, a lightweight markup language that’s easy to write and read.

  3. Themes - MkDocs has several built-in themes for styling your documentation sites, including Material and Read the Docs. You can also create your own custom theme if you want something unique.

  4. Markdown extensions - MkDocs supports various Markdown extensions that provide extra functionality, such as tables, footnotes, and admonitions (like warnings or notes).

  5. Plugins - MkDocs has a growing collection of plugins that add additional features to the generator, like search functionality, table of contents, and more.

  6. Command-line interface - MkDocs provides a simple command-line interface for building your documentation site and deploying it to various hosting platforms.

Overall, MkDocs is an excellent tool for creating clean, well-structured, and easy-to-read project documentation with minimal effort.

Get started with the online documentation at https://www.mkdocs.org/

Publishing websites#

Hosting the websites online is possible at IN2P3 through the GitLab platform https://gitlab.in2p3.fr/ hosted ad CC-IN2P3.

The associated service is called GitLab pages and its general documentation can be found here.

An easy way to get started is to use a project template for a website.
The choice of template is made when starting a new project on GitLab and selecting
Create from template.

Tip

I recommend to use the Pages/Plain HTML template for beginners. It will contain the necessary information to get you started with your first webpage.

You can also get some inspiration by browsing other website projects like this one.

Good luck !

Contents