search

gbv / coli-conc.gbv.de

project coli-conc homepage
https://coli-conc.gbv.de/
5 stars 4 forks source link
coli-conc

readme

coli-conc Website

Install and Build

The website uses Eleventy as a static site generator. Eleventy is built in JavaScript and we are extending some of its functionality with additional packages, therefore node/npm is necessary.

Installation

git clone https://github.com/gbv/coli-conc.gbv.de.git
cd coli-conc.gbv.de
npm install

Build

As we are doing some things that are currently not possible with native Eleventy functionality, we are using a build script which wraps around Eleventy's own build process.

npm run build -- --pathprefix=coli-conc.gbv.de --url=https://gbv.github.io
# The site is now available under _site/

This would build the site to be deployed to https://gbv.github.io/coli-conc.gbv.de/. --pathprefix is optional and only needed if the site is not deployed to the root folder of a domain. --url is always necessary.

Development

A hot-reloading development server is included, though it only serves the English version of the site (note that the German version might still be accessible, but only because of an older build; both build and serve use the _site directory).

npm run serve

The site should be served on http://localhost:8080/. If the port is unavailable, the script will increment the port until an available port is found (please refer to the output).

Alternatively, if hot reloading is not required and you would like to locally preview the whole page (including the German version of the site), building the site is quick, and you can use a simple HTTP server like http-server to serve the site:

# Build and run (adjust port if necessary)
PORT=8091; npm run build -- --url=http://localhost:$PORT; npx http-server -p $PORT _site

The site should now be served on http://localhost:8081, including the German version.

Dependencies on Other Services

The website links to several services that have to be run independently from hosting the website. It is likely necessary to configure a proxy so that certain services are correctly served under certain subfolders. The following is a (not yet exhaustive) list of those services:

Notes

Markdown

We use Markdown for most of the content (there's some inline HTML as well). You can find an overview of Markdown's basic syntax here. Files ending in .md always contain Markdown content, but layout files (usually ending in .njk) might also contain Markdown using Nunjucks shortcodes (see below).

Front Matter

Each page (except for _includes files) needs to provide some front matter at the beginning of the file. Front matter looks like this:

---
layout: layouts/page
title: Title of the page
---

... (actual content of the page)

Here are some values you should or can provide:

Nunjucks

We are using Nunjucks as a blog templating engine. You can find the documentation here. You can use Nunjucks everywhere except in _includes files. In the following, I will describe some parts of Nunjucks and some custom shortcodes we have added to make things easier.

URLs

Run all internal URLs through the url filter so that they will point to the correct path:

[some link]({{ "/path/" | url }})

For static assets that stay the same for both the German and the English site (e.g. images and PDFs), use the custom urla filter instead:

![]({{ "/images/myimage.png" | urla }})

Sections

All content should use sections. There is a custom paired shortcode section which can be used for this:

{% section %}
## Optional Heading (always use h2 because it has special styling at the beginning of sections)

Content of this section (can also contain Markdown as usual).

{% endsection %}

You can add one string parameter with CSS classes if necessary, e.g. {% section "text-center" %} for centered text.

Exception: Blog/news posts (with layout: layouts/blog), do NOT use sections here.

Some notes about sections:

<div> with Markdown Content

For some special layout, you can use the custom paired shortcode div to wrap content inside a div:

{% div "css-classes", "margin-left: 10px;" %}

We can have **Markdown content** here.

{% enddiv %}

The first parameter is the string for CSS classes (i.e. the class attribute in HTML), the second parameter are styles (i.e. the style attribute in HTML).

Markdown content inside a HTML tag

If you need to use Markdown inside some other HTML tag, or you need more control, use the markdown paired shortcode:

{% markdown %}
## Heading

Here is a [link]().
{% endmarkdown %}

Dates

If you need to display dates (e.g. a blog post's date), run it through the date filter:

{{ page.date | date("YYYY-MM-DD") }}

Eleventy Supplied Data

Eleventy, the engine that drives this website, supplies certain data for each page. Please refer the the Eleventy documentation for more information.

Content Overview

For most content, you can just navigate to the page on https://gbv.github.io/coli-conc.gbv.de/, scroll to the bottom, and click on "Source" (after "Impressum" and "Datenschutz"). It will forward you to the file for the current page on GitHub where you can edit the content. However, the are some things to note here:

Here's an explanation of some of the folders/files in this project:

Localization

English is the default language and all content should be created in English first (folder en). Then there are two ways to localize the content to German:

  1. Create the exact same file in folder de (same path, same filename) with German content.

  2. Use _data/strings.js to define strings with keys en and de, then use the localize filter in your file like this: {{ strings.mykey | localize }}

    • You can also define these in the current page's front matter (for title and subtitle) or even inline: {{ { en: "English string", de: "German string" } | localize }}

Shared Markdown Content

If there is certain Markdown content that is shared between two or more files, you can use the _includes folder inside the language folders (not the global _includes folder).

Assuming you have a file en/_includes/test.md, you can include that file in your pages as follows:

{% include locale + "/test.md" %}

This file can also be localized by adding the same file inside de/_includes.

Some notes:

How to Use Vue.js

If there is a page with dynamic content, you can use Vue.js (v3) in the following way:

  1. Add the following to your front matter:

    js:
  vue: true

    This will include Vue.js on that page.

  2. Add a <script> tag where you create the Vue app:

    <script>
const { createApp } = Vue
const app = createApp({
  data() {
     return {
        // ...
     }
  },
})
// Required to avoid templating conflicts with Nunjucks
app.config.compilerOptions.delimiters = ['${', '}']
app.mount('#main')
</script>

  3. Now you can refer to your data/computed inside the current page with ${variableName}. You can also use Vue's attribute names (like v-if etc.) on your HTML tags.

Redirects

If you want to have a redirecting page, create a file with only front matter:

---
layout: layouts/base
redirect: https://example.com
---

layout is necessary because the base layout is handling the redirect. The redirect happens both with a meta tag and JavaScript as a fallback.

TO-DOs