Merge pull request #189 from ELIXIR-Belgium/doc-update

More documentation

pages/documentation/custom_branding.md

@@ -5,10 +5,10 @@ title: Branding
 
 The theme is made so one can easily customize the styling and add personal branding to the website.
 
-## Branding in top navigation
+## Branding in the top navigation
 
-Change the icon in the topnav by adding a `main_logo.svg` file in the `assets/img/` directory.
-If you want to use another file format or use a different filename, please specify this in the theme variable section of the `_config.yml` file. For more info on this config file please visit our [Configuring the theme](custom_branding) page.
+Change the icon in the topnav by adding a `main_logo.svg` file in the `/assets/img/` directory.
+If you want to use another file format or use a different filename, please specify this in the theme variable section of the `_config.yml` file. For more info on this config file please visit our [Configuring the theme](configuring_theme) - page.
 
 ```yml
 theme_variables: 
@@ -18,21 +18,62 @@ theme_variables:
 
 ## Theme styling
 
+Bootstrap 5 is used as css library with the goal of reusing as much as possible to prevent a wild growth of classes and to make the html-code more understandable. SASS is used as css-precursor, a more structured and flexible language to describe the css styling. More information about the SASS language can be found [here](https://sass-lang.com/documentation/).
+
+The order in which the css style sheets are loaded is as follows: bootstrap_variables > bootstrap > variables > custom_variables > main_theme_classes > custom_classes. The theme allows you to intervene and customize at different levels:
 
 ### Bootstrap variables
 
+In the `/_sass/bootstrap_variables.scss` file, you can declare variables that can be used by Bootstrap. This is the very first place where one wants to customize their theme for things like:
+
+- Primary, secondary, light and dark theme colors ($primary, $secondary, $light and $dark)
+- The size of H1, H2, p,... ($h1-font-size, $h2-font-size)
+- The color of links and their decoration ($link-color and $link-decoration)
+- The main font ($font-family-sans-serif)
+
+The variables that you can define, and their respective defaults, can be found in the [Bootstrap variables file](https://github.com/ELIXIR-Belgium/elixir-toolkit-theme/blob/main/_sass/bootstrap/_variables.scss). 
+
 
 ### Custom variables
 
+In the `/_sass/custom_variables.scss` file, you can declare variables that can be used by the theme. These are variables that are used by the theme to define the color, background-color, size and more of components like:
+
+- Sidebar background color and sidebar color ($sidebar-bg and $sidebar-color)
+- Background color of the top-navigation ($topnav-bg)
+- Background color of the footer ($footer-bg)
+- Size of the branding logo in the top-navigation ($topnav-brand-heigh)
+
+The variables that you can define, and their respective defaults, can be found in the [theme variables file](https://github.com/ELIXIR-Belgium/elixir-toolkit-theme/blob/main/_sass/_variables.scss). 
 
 ### Custom classes
 
+In situations where the bootstrap and theme variables are not sufficient, one can add/overwrite css rules using the `/_sass/custom_classes.scss` file.
+This file is loaded as last and can overwrite everything in the theme if needed. This is more used for customizations for theme users that are familiar with css to change things like:
+
+- The distance between headings
+- Adding a shadow to pictures
+- Making sure the branding logo goes smaller in mobile mode
+
+To have some inspiration on what is possible here, go to the [RDMkit custom classes stylesheet](https://github.com/elixir-europe/rdmkit/blob/master/_sass/_custom_classes.scss).
+
+## Favicon logo
 
+"A favicon, also known as a shortcut icon, website icon, tab icon, URL icon, or bookmark icon, is a file containing one or more small icons associated with a particular website or web page." - [Wikipedia](https://en.wikipedia.org/wiki/Favicon).
 
-## Favicon and other metadata fields
+The one from the ELIXIR Toolkit Theme are defined in the `/assets/img` as:
 
+- /assets/img/android-chrome-192x192.png
+- /assets/img/android-chrome-512x512.png
+- /assets/img/apple-touch-icon.png
+- /assets/img/favicon-16x16.png
+- /assets/img/favicon-32x32.png
+- /assets/img/favicon.ico
+- /assets/img/site.webmanifest
+- /assets/img/safari-pinned-tab.svg
 
+This files can be overwritten in your own project by placing them in the same directory with the same name. These files can be easily generated out of an image of your square logo (preferably in svg) with for example the [Favicon generator](https://realfavicongenerator.net/).
 
 ## Branding in footer
 
 
+The footer is one more place to add branding or important logo's. For more information on how to customize the footer, visit our [navigation structures](navigation_structures#footer) page.

pages/documentation/getting_started.md

@@ -2,13 +2,40 @@
 title: Getting started
 ---
 
-## Fork our basic example
+Please follow following steps to use the theme.
 
-To help you started we made a [very basic repository](https://github.com/ELIXIR-Belgium/elixir-toolkit-theme-example) that can be used as template for your upcoming Jekyll website using our theme. 
 
+### 1. Fork the example repository
 
-## Enable GitHub pages
+Go to the [example repository](https://github.com/ELIXIR-Belgium/elixir-toolkit-theme-example) (IMPORTANT). Click on the `Fork` button in the top right of GitHub to fork the repository.
 
-Deploy your website using GitHub pages by enabling it on your repository. Visit the [GitHub documentation](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/) to find out more about how to setup GitHub pages. 
+{% include callout.html type="note" content="The [example repository](https://github.com/ELIXIR-Belgium/elixir-toolkit-theme-example) repo should demonstrate how easy it is to setup the theme, but more importantly, to show how small the amount is you need. It is the bare bone start you want when using the theme from scratch. This way of using the theme will also make sure that your own content is not cluttered with theme files and that you can easily stay up to date when improvements to the theme are made." %}
 
+### 2. Deploy using GitHub Actions
 
+1. Go to Settings > Pages and enable GitHub Actions as a source
+2. Go to Environments > github-pages and remove the rule under Deployment branches if you want to deploy other branches than master or main via Workflow Dispatch (manually triggered action)
+3. Push a change to master/main branch and the GitHub Actions will be triggered.
+
+**Deploy using GitHub Pages (alternative)**
+
+This is the quickest way to deploy the elixir-toolkit-theme, but gives less flexibility and does not allow you to make use of the new way of tagging tools. Visit the [GitHub documentation](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/) to find out more about how to setup GitHub pages. 
+
+NOTE: This way of deploying does not support the tool-tag in the text of the Markdown file to tag tools and resources.
+
+### 3. Checking out your deployment
+
+After waiting a minute or two (deployments can take  a while), you can checkout your website. THe deployment is by default served at https://USER.github.io/FORK-NAME/. 
+
+### 4. Making changes
+
+Any change to the master/main branch will automatically trigger the re-deployment of the website, so your changes come live. More information on how you can configure the theme can be found on the other documentation pages: 
+
+- [Changing the navigation structures](navigation_structures)
+- [Configuring the theme](configuring_theme)
+- [Applying custom branding](custom_branding)
+- [Markdown cheat sheet](markdown_cheat_sheet)
+
+### 5. Add a LICENSE file to your GitHub repository. 
+
+Add a license to your repository using the [GitHub instructions](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository).

pages/documentation/navigation_structures.md

@@ -3,16 +3,146 @@ title: Navigation structure
 contributors: [Bert Droesbeke]
 ---
 
+The theme tries to minimize the need to change html code as much as possible, and for the top navigation, sidebar and footer, this is not different. These navigation structures are all defined by YAML files as  explained below.
+
 ## Top navigation
 
+The top navigation links are defined by the the `/_data/topnav.yml` file under the `subitems:` object. Components like search, Github (or GitLab) and main logo are rendered by default and can not be changed.
+
+```yml
+subitems:
+- title: Home
+  url: /
+```
+
+Dropdown can be added in a similar way by nesting subitems:
+
+```yml
+subitems:
+- title: Example dropdown
+  subitems:
+  - title: Events
+    url: /events
+```
+
+External urls can be specified using:
+
+```yml
+subitems:
+- title: Home
+  external_url: https://example.url
+```
+
+{% include callout.html type="important" content="Make sure the given url follows the exact structure of the url your page is rendering to." %}
 
+Certain elements have options in the `/_config.yml` file as described in the [configuring theme](configuring_theme) page. Style customizations are described in the [custom branding](custom_branding#branding-in-the-top-navigation) page.
 
 ## Sidebar
 
+This theme supports multiple sidebars, defined by YAML files in the `/_data/sidebars` directory. Changing these yaml file will immediately impact the sidebars and the frontpage of the website without the need of changing any HTML code. The sidebar that will be displayed on a specific page is defined by the [metadata of that page](page_mechanics). The sidebar supports multiple levels (up to 3) and each level in the hierarchy can contain a URL to a page within this website or an external URL.
+
+The attributes that define the structure are:
+- `title`: This is the text that will show up in the sidebar.
+- `url`: The URL to the internal page you want to link to. This is mostly in the form of: */markdown_file_name.html*.
+- `external_url`: Use this instead of URL if you want to link to an external page.
+- `subitems`: to define a sublevel.
+- `hr`: THis can be set as true to add a horizontal spacer (top) between 2 subitems in the sidebar. (example: `hr: true`)
+
+Example:
+
+```yaml
+- title: Level_1_title
+  url: level_1_url
+  subitems:
+    - title: Level_2_title
+      url: level_2_url
+```
+
+The sidebar also allows you to specify a sidebar title, version and title url using following syntax:
+
+
+```yml
+title: About
+version: 2.0
+title_url:  /events
+```
 
 ## Top navigation and sidebar relationship
 
+Top navigation titles can be used to switch between different high level sections on the website, each having their own sidebar. As described before, sidebars are defined by the `sidebar` metadata attribute in a page, so linking in the topnav YAML towards whis page is one part of the job. To make sure that all pages within that sidebar have this topnav item on active, one has to name its sidebar file in the same way as the topnav title (spaces, hyphens and underscores get ignored). 
+
+Example: `/_data/sidebars/main_sidebar.yml` and in the `/_data/topnav.yml`:
+
+```yml
+subitems:
+- title: Main sidebar
+  url: /
+```
 
 ## Footer
 
+Just like the other navigation structures, is the footer defined by a YAML file, `/_data/footer.yml`.
+The footer is composed out of columns, of which the width is defined by integers between 1 and 12, and the total of all columns should not exceed 12.
+
+
+Lets dissect the footer structure using this below: 
+
+```yml
+copyright: Copyright notice
+extra_line: 
+columns:
+  - type: image
+    image_width: 150px
+    width: 3
+    src: 'images/infrastructures/ELIXIR_BELGIUM_white_background.svg'
+    alt: ELIXIR Belgium logo
+  - type: links
+    title: Title
+    width: 3
+    children: 
+      - url_text: Contributors
+        url: /contributors
+      - url_text: Getting started
+        url: /getting_started
+  - type: links
+    width: 3
+    children: 
+      - url_text: About
+        url: /about
+      - url_text: Accessibility
+        url: /accessibility
+      - url_text: Privacy
+        url: /privacy
+  - type: image
+    image_width: 100px
+    width: 2
+    src: 'assets/img/Flag_of_Europe.svg'
+    alt: European flag
+  - type: image
+    image_width: 88px
+    width: 1
+    src: 'assets/img/ett_compact_logo.svg'
+    alt: Jekyll Bootstrap theme logo
+```
+
+High level attributes:
+
+* `copyright`: Define the text in the most bottom part of the footer, usually with a darker background and describing the license.
+* `extra_line`: Add a extra line in the top part, spanning the full width of the footer (optional)
+* `columns`: Key to list columns
+
+Column attributes:
+
+* `type:`: This defines the purpose of the column and can be *links* or *image*
+* `image_width`: To be specified when it is an *image* column, don't forget to add the unit.
+* `width`: Integer, defining the width of the column. Total sum of all columns should be 12.
+* `src`: Absolute path to the image. To be specified when it is an *image* column
+* `alt`: Alt text of the image. To be specified when it is an *image* column
+* `title`: Title of a column with type *links* (optional)
+* `children`: Key to list links in a column with type *links*
+* `url_text`: Title of a link.
+* `url`: Absolute path of a page.
+
+
+
 

pages/documentation/page_mechanics.md

@@ -10,14 +10,16 @@ title: Title of the page
 ---
 ```
 
+It is important to know that you can also set the these key-value pairs on multiple pages at the same time by specifying them in the `_config.yml` file as described in the [Jekyll documentation](https://jekyllrb.com/docs/configuration/front-matter-defaults/).
+
 ## Possible metadata attributes of a page
 
 
 * `title`: Specify here the title of the page. This wil be the H1 title (replacing the top level title using the # in markdown )
 
-* `summary`: Using this attribute it is possible to specify a summary which will be displayed under the title of the page. This summary will also be used as description of your page when the page is tagged.
+* `summary`: Using this attribute it is possible to specify a summary which will be displayed under the title of the page.
 
-* `description`: Short sentence about the page starting with a lowercase. This sentence is visualized when pages are automatically listed using a tag.
+* `description`: Short sentence about the page starting with a lowercase. This sentence is visualized when in the related pages section of a page..
 
 * `contributors`: list here all the contributors that helped in establishing the page. This will be the full name of the person. Make sure that the person name that is listed can be found in the CONTRIBUTORS.yaml file in the _data directory if you want to link the github id and other contact information.
 
@@ -39,18 +41,22 @@ title: Title of the page
 
 * `datatable`: use this attribute to activate the pagination + sorting + searching in tables
 
+* `type`: The type of page, used for [website sections](website_sections).
+
+* `sidebar`: the name of the sidebar file that needs to be used on this page.
+
 
 ### Related pages
 
-* `related_pages`: List here the `page_id` of {{site.title}} pages that you want to display as Related pages, grouped by section.
+* `related_pages`: List here the `page_id` of your pages that you want to display as under the Related pages of this page, grouped by section. See [website sections](website_sections) for more information.
 
-  If you want pages from the specific section (Your tasks, Your domain, Tool assembly) to be shown here as Related pages, list their `page_id`. If you want to list multiple related pages, make sure to put them in a list like this: [page_id1, page_id2]. The specific sections allowed in each page are specified in each page template. Please, do not add extra sections in the metadata of the page.
+  If you want pages from the specific section to be shown here as Related pages, list their `page_id`. If you want to list multiple related pages, make sure to put them in a list like this: [page_id1, page_id2]. The specific sections allowed in each page are specified in each page template. Please, do not add extra sections in the metadata of the page.
 
   ```yml
   related_pages: 
-    - your_tasks: [page_id1, page_id2]
-    - your_domain: [page_id1, page_id2]
-    - tool_assembly: [page_id1, page_id2]
+    - section_name: [page_id1, page_id2]
+    - section_name: [page_id1, page_id2]
+    - section_name: [page_id1, page_id2]
   ``` 
 
 

pages/documentation/website_sections.md

@@ -2,6 +2,62 @@
 title: Website sections
 ---
 
-## 
+When content grows, the need to categorize grows. The theme makes it possible to categorize in the [sidebar](navigation_structures#sidebar), but also to list pages in a nice way that belong to the same section.
 
+A section is simple a collection of pages of the same `type`, see [page mechanics](page_mechanics). Adding the pages you want to list in an overview, can be simply done by tagging them with a type (in the example `type: example_pages`) in the metadata and listing that type using the snippets below.
 
+
+## Section tiles with information
+```
+{% raw %}
+{% include section-navigation-tiles.html type="example_pages" affiliations=true search=true except="index.md" %}
+{% endraw %}
+```
+
+Becomes:
+
+{% include section-navigation-tiles.html type="example_pages" affiliations=true search=true except="index.md" %}
+
+### Parameters
+
+* `affiliations`: Turn on filtering by affiliation (`true` or `false`)
+* `search`: enable search in the tiles (`true` or `false`)
+* `except`: `, ` separated list of page file names which should be excluded, including the file extension.
+* `col`: give an integer to specify the number of columns/section cards per row. Default: 2.
+
+
+## Section tiles simple
+
+```
+{% raw %}
+{% include section-navigation-tiles-simple.html type="example_pages" %}
+{% endraw %}
+```
+
+
+{% include section-navigation-tiles-simple.html type="example_pages" %}
+
+### Parameters
+
+* `except`: `, ` separated list of page names which should be excluded, including the file extension.
+* `col`: give an integer to specify the number of columns/section cards per row. Default: 2.
+
+
+
+## A more clever way of tagging pages with a certain type
+
+It is important to know that you can also set the these key-value pairs on multiple pages at the same time by specifying them in the `_config.yml` file as described in the [Jekyll documentation](https://jekyllrb.com/docs/configuration/front-matter-defaults/) using the frontmatter defaults.
+
+Example
+
+```yml
+defaults:
+  -
+    scope:
+      path: "pages/data_life_cycle"
+    values:
+      type: data_life_cycle
+
+```
+
+This will give all markdown files in the `pages/data_life_cycle` subdirectory the *data_life_cycle* type.

pages/example_pages/logo_page.md

@@ -4,8 +4,8 @@ title: Logo page
 
 ```
 {% raw %}
-{% include affiliation-tiles-selection.html type="funder"%}
+{% include affiliation-tiles-selection.html type="funder" %}
 {% endraw %}
 ```
 
-{% include affiliation-tiles-selection.html type="funder"%}
+{% include affiliation-tiles-selection.html type="funder" %}