A Pelican theme for the TDWG website.
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
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"
]
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)
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
.
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).
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).
- Clone this repo:
git clone https://github.com/tdwg/tdwg-theme
- Verify npm is installed:
node -v
(tested with 3.10) - Go to the root of this repository
- Install all dependencies with:
npm install
(will read package.json to create thenode_modules
directory)
- Go to the
src/scss
- Update the relevant
.scss
files - Generate the CSS in
static/css
automatically on every change withnpm run watch:css
- Go to the
src/js
- Update or add the relevant
.js
files - Copy the JS to
static/js
automatically on every change withnpm 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