Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
bin
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Talc

codecov

Talc is my experiment to create blog posts from Markdown files and, eventually, a static site.

How to Use

Add an NPM Task

In your package.json add:

{
  "scripts": {
    "talc": "talc"
  }
}

Create a Talc Config

Talc looks for a talc.config.js file next to your package.json. It understands the following attributes:

Attribute Type Purpose Default Value
built string Directory where compiled post will live "built"
dateFormat string The Luxon date format to use "yyyy-MM-dd HH:mm:ss"
drafts string Directory where draft posts live "drafts"
pages Pages The different pages to render and (optionally) the directory where they live { templates: [] }
published string Directory where posts that will be compiled live "published"

The Pages Config

The pages that will be created rely on templates which can be provided by the pages attribute of talc.config.js. There are two attributes:

Attribute Type Purpose Default Value
directory string The directory where the templates live undefined
partials string The directory where partial templates live undefined
templates Array<Template> The list of templates to create []

Each Template can have the following attributes:

Attribute Type Purpose Default Value
sortBy Array<string> A list of metadata variables to sort by; only applies to "listing" templates ["publish_date"]
template string The filename of the source template N/A; required
transformer Function A way of pre-processing a template; only applies to "listing" templates (files, template) => [{ filename: template.filename, files }]
type "listing"|"post" The filename of the source template "post"

Transformers

More than meets the eye!

A transformer allows the processing of a template to add metadata or even return multiple templates.

The function signature for a transformer is:

(files: Array<File>, template: Template) => Array<TransformedFile>

The input parameters are:

Attribute Type Purpose
files Array<File> The list of process "post" files
template Template The original template

Each File will contain the file's filename and any metadata coming from the original markdown file.

A TransformedFile can have the following attributes:

Attribute Type Purpose Required?
filename string A new filename to use for the derived file
files Array<File> The files to use when processing the template 👍
metadata Object Any additional metadata to use on the template
template string An alternative template to use

Generate a New Markdown File

Talc can create a Markdown file for you with a title:

$> npm run talc new "My New Post"
# or
$> npm run talc n "My New Post"

Publish a File

Talc will append a publish_date and move your file to the published directory from the drafts directory:

$> npm run talc publish my-file
# or
$> npm run talc p my-file

Notes:

  1. If a file has no metadata boundaries (---) it'll be silently skipped
  2. If a file has multiple publish_date attributes, the last in the list of metadata is the one used

Convert to HTML

To convert all of the Markdown files in the config.output directory, run the following command:

$> npm run talc build
# or
$> npm run talc b

Using a Template File

In order to place content into a template, create any HTML document and, where the content should go put a comment with talc:content in it:

<html>
  <head>
    <title>My Template</title>
  </head>

  <body>
    <div class="content">
      <!-- talc:content -->
    </div>
  </body>
</html>

Template Partials

Sometimes we have HTML that we use over and over again. For instance, the header of your page might be the same text on every page. Instead of adding that HTML to every template, you can leverage template partials to make reusable code.

You could break up your reusable content into separate, reusable partials:

<!-- templates/header.html -->
<html>
  <head>
    <title>My Template</title>

    <link rel="stylesheet" href="styles/my-styles.css">
  </head>

  <body>
    <header>
      <h1>My Awesome Page!</h1>
    </header>

    <div class="content">
<!-- templates/footer.html -->
    </div>

    <footer>
      (C) 1981, Awesome Page Inc.
    </footer>
  </body>
</html>

And then, in your actual content templates, reference those templates, by using talc:import:<template>, to have them compiled when publishing:

<!-- templates/post.html -->
<!-- talc:import:header.html -->
<!-- talc:content -->
<!-- talc:import:footer.html -->

Combining templates, partials, and variables (see below) allows minimal code while allowing for multiple page formats.

Metadata & Variables

Talc supports the use of Markdown metadata to allow you to leverage that metadata as variables in your templates.

For a post like:

---
title: My Boy is Born!
publish_date: 2018-08-03 08:01:00
tags: birth,baby,happy
---

Today was a glorious day! My son was born!

And a template like:

<html>
  <head>
    <title>Post: <!-- talc:title --></title>
  </head>

  <body>
    <h1><!-- talc:title --></h1>
    <span class="dateline"><!-- talc:publish_date --></span>

    <!-- talc:content -->

    <ul class="tags">
      <!-- talc:for:tags -->
      <li><!-- talc:content --></li>
      <!-- talc:endfor -->
    </ul>
  </body>
</html>

The output file would look like:

<html>
  <head>
    <title>Post: My Boy is Born!</title>
  </head>
  <body>
    <h1>My Boy is Born!</h1>
    <span class="dateline">8/13/2018</span>
    <p>
      Today was a glorious day! My son was born!
    </p>
    <ul class="tags">
      <li>birth</li>
      <li>baby</li>
      <li>happy</li>
    </ul>
  </body>
</html>

Special Metadata/Variables

Talc has a small set of special, known metadata. The provided variables will not be recognized if placed in metadata.

Variable Purpose Required? Provided?
content This outputs any text content; if in a loop it'll output the value at the current index 👍
create_date Specify the date the content was created; Talc will use the dateFormat config attribute to format the output of this attribute
files Only available to a "listing" template, this provides an array of file metadata including the filename and any data for that file 👍
publish_date Specify the date the content moves to a published state; Talc will use the dateFormat config attribute to format the output of this attribute 👍
title The title of the content 👍

Loops & Listing Templates

As the example above shows, Talc supports the use of a very simple for/endfor looping construct. The basic syntax is:

<!-- talc:for:{variable name} -->
...do some stuff here...
<!-- talc:endfor -->

The metadata of a markdown file only supports very simple lists, so any metadata array should use <!-- talc:content --> to output the value at each index of that array.

For the special variable files (which is only available to a "listing" template), Talc will provide all of the metadata and filename for each file in the array. Those metadata & filename can be used as output just by referencing their variable name. So to output a list of all filenames and their publish dates, you could write an "listing" template like:

<ul>
  <!-- talc:for:files -->
  <li>
    <!-- talc:filename -->
    (<!-- talc:publish_date -->)
  </li>
  <!-- talc:endfor -->
</ul>

This template just loops through files and, for each value in the files array, uses the filename and publish_date metadata attributes to fill in the content.

If you had a tags metadata on some (or all) of your posts that you wanted to output, you could create a nested loop and use talc:content to output the value of each value in the tags array:

<ul>
  <!-- talc:for:files -->
  <li>
    <!-- talc:filename -->
    (<!-- talc:publish_date -->)
    <div class="tags">
      <!-- talc:for:tags -->
      <div class="tag"><!-- talc:content --></div>
      <!-- talc:endfor -->
    </div>
  </li>
  <!-- talc:endfor -->
</ul>

About

Talc is an experiment to create posts from Markdown

Topics

Resources

Packages

No packages published