Human-IST Minisite boilerplate

This boilerplate serves as a base for Human-IST mini-websites. These are meant to host additional material for courses, events, or personal pages, as the main website is mostly static and requires specific access for modifications. This boilerplate assumes that you have an understanding of HTML and terminal use.

Directory structure

The project is structured into different directories:

• content: all the pages of the website
• dist: the built, production-ready version of the website
• public: the public documents you want to make accessible to the visitors
• src: code source of the boilerplate
• tests: (to implement) unit and e2e tests for the boilerplate

Using this boilerplate

Installing dependencies

If you want to create a new Human-IST Minisite, you need to have some dependencies installed. First, make sure you have NodeJS installed on your computer. Then, install the npm's dependencies by accessing the root folder of this project in a terminal, then typing npm install # or yarn install.

Configure the mini-website

Open the file content/config.json in a text editor and change its values according to your needs.

• title: the title of this mini-website. Will be display in a H1 tag at the top left of the website;
• subtitle (optional): a subtitle displayed just below the title, in a H2 tag;
• meta: all other data you would like to display on every page, next to the subtitle;
• url: the url of the mini-site on the human-ist.institute website. For instance, if you want to access this mini-website under https://human-ist.institute/test, set this property to "test".

Adding pages and structure

All the logic of this boilerplate lies in Markdown files, that you will have to write. These reside in the content/pages/ directory - take a look at the example to understand how they work. Basically, everything that lies between the two --- are metadata about the page.

• url: the url of the page;
• parent (optional): the identifier of another page that this page should be related to (if any). This identifier is equivalent to the name of the parent's markdown file, minus the extension (if the parent page is "example.md", the property should be set to "example");
• background: the name of an image that will serve as the banner of the page. The image must be placed under the public/img/ directory);
• title: the human-readable title that will be shown on the page;
• description: the description of the page, used in the HTML head's metadata;
• order: the position of the page relative to others. Please make sure that you do not have twice the same number, and that the numbers are following without gap.

The rest of the content consists of regular Markdown, which is fairly easy to use. If you need help with Markdown, please check this guide. For a more specific list of supported special commands, check this page.

On top of that, there exist a custom command to create dropdowns like this one. **Click here** to learn mroe about this.

``` [dropdown]{Title} Content [\dropdown] ``` Or, to have the dropdown open by default: ``` [dropdown!]{Title} Content [\dropdown] ```

Compiling the pages into a single JSON file

When all the pages are finished, you can compile them into a single file that will be served to the visitors of the website. To do so, open a terminal, reach the root folder of this project, and type npm run compile # or yarn compile. It should create a file called pages.json at the root of the content/ directory. Note: if you are planning to use the development version of the minisite (see below), use npm run compile --dev # or yarn compile --dev to avoid issue with public resources.

---

Development

WIP