Triven

A multi-language markdown-based blog generator.

Installation

npm install -D @glorious/triven

Usage

To get started with Triven, you need to run the following command at the root directory of your project:

npx triven build

After running this command, a directory called triven and a demo post will be created.

Setup

You don't need to setup anything to see Triven in action. By default, Triven will look for markdown files in the project directory (and sub-directories) and will generate a blog - ready to be published - inside a directory called triven.

However, you can override the default configuration values used to build your blog creating a file called triven.config.js in the root directory of your project containing the following options:

1// triven.config.js
2
3module.exports = {
4  title: 'Your Blog Title',
5  // [Required] Used as browser window title on homepage.
6  // Default: Triven.
7  url: 'https://rafaelcamargo.com/blog',
8  // [Required ]Production URL where the blog will be deployed to.
9  // Used to build absolute URLs on RSS Feeds.
10  sourceDirectory: './posts',
11  // Directory where triven will look for markdown files.
12  // Default: Root directory of your project ('./').
13  outputDirectory: './dist',
14  // Directory where the final files will be saved.
15  // Default: './triven'.
16  lang: 'pt-BR',
17  // Used as default language for articles and homepage.
18  // Default: en-US.
19  homepagePostIntroType: 'description',
20  // Content to be used as post introduction on homepage.
21  // Options:
22  // 1. Post Excerpt: 'excerpt'
23  // 2. Post Description: 'description'
24  // Default: 'excerpt'.
25  // Note: Excerpts are automatically generated using
26  // the first 340 characters of the post body.
27  templates: {
28    article: './some/path/to/article/template.html',
29    // You can optionally set an HTML file as template for articles
30    homepage: './some/path/to/homepage/template.html',
31    // You can optionally set an HTML file as template for homepage
32    vars: {
33      // You can optionally set variables in your templates
34      // to be replaced with custom values in build time:
35      someVar: 'someValue',
36      // If a variable depends on the page language,
37      // you can set a function as value to handle any custom logic:
38      greet: lang => lang == 'pt-BR' ? 'Olá' : 'Hello!'
39    }
40  },
41  // You can optionally set custom translations for labels used by Triven:
42  translations: {
43    'en-US': {
44      availableRSSFeeds: 'RSS Feed options',      // Default: 'Available RSS Feeds'
45      availableLanguages: 'Language options',     // Default: 'Available languages'
46      currentLanguage: 'Selected language',       // Default: 'Current language'
47      multiLanguage: 'All languages',             // Default: 'Multi-language'
48      newer: 'Previous page',                     // Default: 'Newer'
49      older: 'Next page',                         // Default: 'Older'
50      readMore: 'Keep reading',                   // Default: 'Read more'
51      rssFeed: 'Feed',                            // Default: 'RSS Feed'
52      rssFeeds: 'Feeds',                          // Default: 'RSS Feeds'
53      seeAllPosts: 'All publications'             // Default: 'See all posts'
54    },
55    // You can add specific-language dictionaries if you have a multi-language blog:
56    'pt-BR': {
57      // Portuguese translations
58    }
59  },
60  formatters: {
61    // You can optionally set a custom date formatter.
62    // Formatter will receive the date string and the language set on the
63    // respective post markdown file.
64    // By default, date format will be month/day/year for US English posts and
65    // day/month/year for any other language.
66    date: (isoDateString, lang) => {
67      const [year, month, day] = isoDateString.split('-');
68      const date = new Date(parseInt(year), parseInt(month)-1, parseInt(day), 0);
69      const options = { day: 'numeric', month: 'long', year: 'numeric' }
70      return Intl.DateTimeFormat(lang, options).format(date);
71    }
72  }
73}

Markdown Articles

You can prefix your Markdown articles with a header containing some metadata:

Name	Description	Default Value
title	Title for your post	Untitled
lang	Language which your article is written in	language set on triven.config.js or en-US
date	Date expressed according to ISO 8601 (YYYY-MM-DD)
description	A brief description of your post (used in HTML meta tags)
keywords	Keywords for your post (used in HTML meta tags)
unlisted	Set as true to keep the post out of homepages
externalUrl	URL for a post published in an external website
excerpt	An optional text representing the first paragraphs of your post	First 340 chars of your post

Important: Do not forget to separate your article from its metadata with three dashes.

Markdown Example

// hello-world.md

title: Hello World!
date: 2021-08-20
description: Saying hello to the world.
keywords: hello, world

---

It's very easy to get started with Triven.

Custom Templates

You can define your own HTML to be used as template for homepage and article. Just make sure that your HTML contain at least the following markup:

Homepage

1<!DOCTYPE html>
2<html>
3  <head></head>
4  <body>
5    {{ triven:posts }}
6    {{ triven:settings }}
7  </body>
8</html>

• triven:posts: List of posts.
• triven:settings: Language and RSS selectors (for multi-language blogs).

Article

1<!DOCTYPE html>
2<html>
3  <head></head>
4  <body>
5    {{ triven:article }}
6    {{ triven:footer }}
7  </body>
8</html>

• triven:article: Post content.
• triven:footer: Container for the "See all posts" link.

You can optionally set variables in your templates to be replaced in build time. To do so, you need define them as key/value pairs in your triven.config.js, and reference them in your template HTML file as follow:

1// triven.config.js
2
3const date = new Date();
4
5module.exports = {
6  templates: {
7    vars: {
8      copywrite: `©${date.getFullYear()} Triven`
9    }
10  }
11}

1<!DOCTYPE html>
2<html>
3  <head></head>
4  <body>
5    {{ triven:posts }}
6    {{ triven:settings }}
7    <footer>
8      {{ copywrite }}
9    </footer>
10  </body>
11</html>

Note: Variables in templates are space insensitive. You can write them as {{copywrite}} or {{ copywrite }}.

Contributing

If you want to contribute to this project, follow these instructions.