Kodama

Summary

This theme is greatly inspired from hugo academic theme.

First lets introduce some technical details:

• It relies on zola.
• It has no javascript.
• The CSS is built with tailwindcss.
  • The blog articles are themed with @tailwindcss/typography theme.

Getting started

The best way to get started is to follow the official zola tutorial.

This theme can be installed as any other theme.

mkdir themes
cd themes & git clone https://github.com/adfaure/kodama-theme

and set in the config.toml the variable theme to kodama-theme.

Generate the CSS

Tailwindcss is a framework that parses your html files, and generate the minimal CSS required. This theme depends on this framework.

The theme comes with the precompiled style files (static/styles/styles.css). However, if you wish to change the style, or modify the template htlm, you might need to recompile your styles.

The most simple way, is to follow the installation page of tailwindcss.

At the end, you should have tailwindcss installed, and I advise to use the following tailwind configuration:

# tailwind.config.js
module.exports = {
  content: ["./templates/**/*.html", "./themes/**/*.html",  "./themes/**/*.html"],
  theme: {},
  variants: {},
  plugins: [
      require('@tailwindcss/typography'),
  ],
};

Create a file styles/styles.css, and use the following command to generate the final CSS file:

npx tailwindcss -i styles/styles.css -o static/styles/styles.css

The resulting file static/styles/styles.css is loaded in the html.

Note that, for the moment the generation of the css is not automated. As a result, it is necessary to re-run this command when changes are made with the styling.

Configuration

This theme use some extra configuration, that can be set in the extra section of your config.toml.

# Title displayed in the index page
title = "Website title"

# Use this theme
theme = "kodama-theme"

[extra]

# Image of your avatar displayed on the landing page
avatar = "static/img/avatar.jpg"
# Image of the favicon
favicon = "static/img/avatar.jpg"

# Your email address showed in the contact section
email = "kodama[at]domain.com"

# If you don't want to show your contact information in the index
contact_in_index = true

# Additional menu items
# `Name` is what it is displayed, `path` is the url
menu_items = [
  { path = "#contacts", name = "Contact" },
]

Index page

The information needed to build the index page are located in the page front matter of root index file (e.g content/_index.md).

The available configuration options are:

# Insert zola front matter variable such as date etc

[extra]

# Show a concise description of what you do below your avatar.
title = "Concise description"

# The list of interests displayed
interests = [
  "Rainbow pony",
  "Martian food",
  "Quantic science"
]

# The list of your degrees / education
[[extra.education.courses]]
  course = "Latest degree"
  institution = "Some acamedy"
  year = 2020

[[extra.education.courses]]
  course = "Another degree"
  institution = "Here and there"
  year = 2016

# Finally, a list of icons with a link displayed below your avatar
[[extra.avatar_icons]]
  icon = "github"
  link = "https://github.com/adfaure"
[[extra.avatar_icons]]
  icon = "gitlab"
  link = "https://gitlab.com/adfaure"
[[extra.avatar_icons]]
  icon = "linkedin"
  link = "https://www.linkedin.com/in/adrien-faure-9958978b/"

Contact

The predefined contact page can be use. The front matter extra part should contains a list of the link to show in the contacts.

Sections

The section available in your website are automatically detected and displayed in the nav bar at the top of the page. To prevent a section to be displayed in the nav bar, you can set the extra front matter option extra.hidden_nav = false to false.

The section are sorted by weight defined in the front matter of the section.

By default, the sections (i.e folders under content/section_name) have a summary showed in the index. This is configurable in the front matter of the section (e.g content/section_name/_index.md).

# The name displayed in the section summary
extra.index_title = "Recent Posts"
# Set to false to remove the section from the index
extra.index_show = true

Blog

The section blog is the most standard section. It show a list of article with things that you want to share in your website. To use the blog template, configure the section with the following front matter:

template = "section.html"
page_template = "blog-page.html"

Publications

The section publication is very similar to the blog section however it is dedicated to show your list of scientific articles. The articles are showed in two subcategories: Thesis and Conference / Workshop.

To configure a publication section (e.g content/research) and set the following content:

+++
title = "Research"
sort_by = "date"

# Here the two dedicated templates
template = "publications.html"
page_template = "publication-page.html"

# If you want to show your publications under different sections
# the title will be the displayed text in your website, and the type
# should be the type of publication.
# Each individual plublication has an `extra.type` that refers to the
# publication type (example in content sub-section).
extra.publications_types = [
  { title = "Journal articles", type = "journals" },
  { title = "Thesis", type = "thesis" },
  { title = "Conferences and workshops ", type = "conferences" }
]
+++

## Content

Any content will be displayed on top of the section.

Article are referenced in subdirectories of this section.

tree content/research
content/research
├── _index.md
├── paper1
│   ├── bib
│   └── index.md
└── thesis
    ├── bib
    ├── index.md
    ├── thesis.pdf
    └── thesis_slides.pdf

The bib files are automatically loaded to get information from it. However, it is also possible to add information in the front matter of the article markdown file.

+++
title = "Article 1"
date = 2021-05-18

[extra]
type = "Conference"
authors = [ "Kodama Mononoke" ]

# Should be the type of the publication type it should appears under
# configured in the front matter of publications/_index.md
type = "conferences"

featured = true
publication = "2020 IEE rainbow workshop"
# Add full url for your pdf and your presentation
url_pdf = "https://your-pdf"
url_slides = "path_to_slides"

# Add a link to a local pdf inside of your paper folder (example in content/publications/paper1.index.md)
pdf = "paper.pdf"
slides = "path_to_slides.pdf"
+++

Extend the html header

In some cases, it is needed to add extra javascript or css files to be loaded by the web browsers. The base template of this theme define an empty block named user_head.

To use this block, you can just create a new template name templates/base.html with the following content:

{% extends "kodama-theme/templates/base.html" %}

{% block user_head %}
  <script>
    console.log("hello world!");
  </script>
{% endblock user_head %}

Icons

The icons available in this project are stored in a dedicated macro function in templates/macros/icons.html. To add a new svg, you can add a case in the if elif .. else of the function containing the svg copied from heroicons for instance.