tdwg / tdwg-theme

Pelican theme for the TDWG website

TDWG theme

A Pelican theme for the TDWG website.

Getting started

This theme was developed for the TDWG website. Although it wouldn't make sense to use it as is for any other website, you're welcome to fork and adapt it. tdwg is only used in the theme name: the rest of the naming is neutral. To get started, download the theme and reference its path in your Pelican settings. For example:

THEME = "../tdwg-theme" # If tdwg-theme is in the same directory as your website repo

Dependencies

This theme makes use of the following Pelican plugins:

• pelican-page-order: to add page_order attribute to pages if one is not defined. Required: throws 'pelican.contents.Page object' has no attribute 'page_order' if not installed.
• pelican-page-hierarchy: to create URL hierarchy for pages matching directory structure. Required: throws 'pelican.contents.Page object' has no attribute 'parents' if not installed.
• pelican-toc: to assign ids to headers in pages/articles and render a table of content.
• pelican-bootstrapify: to add Bootstrap classes to page/article content.
• pelican-github-edit: to add a link to edit pages/articles on GitHub.
• pelican-cover-image: to add cover image URL to pages/articles.
• tipue_search: to enable Javascript site search.
• summary: to only display non-generated summaries as lead paragraph.

Download these plugins to your plugins directory (like here) and define them in your website settings file (see Pelican documentation):

PLUGINS = [
    "pelican-page-order",
    "pelican-page-hierarchy",
    "pelican-toc",
    "pelican-bootstrapify",
    "pelican-github-edit",
    "pelican-cover-image",
    "tipue_search",
    "summary"
]

Repo structure

The repository structure is that of a Pelican theme. Files/directories indicated with GENERATED should not be edited manually.

├── README.md         : Description of this repository
├── LICENSE           : Project license
├── package.json      : npm package description, contains scripts for development
├── .gitignore        : Files and folders to be ignored by git (including node_modules)
│
├── node_modules      : Modules installed by npm, is gitignored. GENERATED
│
├── src
│   ├── js            : Theme specific Javascript files (look here if you want to adapt the JS)
│   └── scss          : Theme specific SCSS (look here if you want to adapt the CSS)
│
├── static            : All static files for this theme. Similar to a "dist" directory. GENERATED
│
└── templates         : Pelican Jinja templates (look here if you want to adapt the HTML)

Development

Bootstrap

This theme uses Bootstrap v4.0 as a framework to create a responsive website. The HTML is entirely structured around Bootstrap classes for layout, content, components and utilities, with as little deviation as possible. The CSS starts from Bootstrap's SCSS/SASS, with custom variable overwrites in src/scss/_variables.scss and custom CSS in src/scss/main.scss. These get bundled together with Bootstrap in a single static/css/main.css.

Update HTML

The HTML is structured in templates with a Jinja syntax. templates/base.html is the main template: all other templates are build upon it. See the Pelican documentation to understand what each template does.

No npm scripts need to be run to make HTML changes effective (the templates directory is read directly by Pelican).

Update SCSS and/or Javascript

To update the SCSS and/or JS, npm is required. It is used to install all dependencies (such as Bootstrap v4.0) and run development scripts (such as generating the CSS from SCSS).

Installation

1. Clone this repo: git clone https://github.com/tdwg/tdwg-theme
2. Verify npm is installed: node -v (tested with 3.10)
3. Go to the root of this repository
4. Install all dependencies with: npm install (will read package.json to create the node_modules directory)

Update SCSS

1. Go to the src/scss
2. Update the relevant .scss files
3. Generate the CSS in static/css automatically on every change with npm run watch:css

Update JS

1. Go to the src/js
2. Update or add the relevant .js files
3. Copy the JS to static/js automatically on every change with npm run watch:js

Important: do not touch files in the static directory: those are all generated! Look for the files in src instead. To completely rebuild the static directory, do npm run build:all

Contributors

List of contributors

License

MIT License