base16-builder / base16-builder

:hammer: Base16 Builder is a nimble command-line tool that generates themes for your favourite programs.

Base16 Builder is a nimble command-line tool that generates themes for your favourite programs. See it in action below:

Base16 Builder is easy to use. All you have to do is supply a color scheme, template, and brightness (light or dark). Base16 Builder will use the information you provide to generate a theme and write it to stdout.

Because Base16 Builder writes to stdout, it's possible to pipe the theme anywhere you like. In the above screencast, the theme is piped to a new file called "theme", but this could just as well have been a configuration file like ".Xresources".

You don't have to be savvy with Unix pipelines to enjoy Base16 Builder. If you'd prefer, you can just copy the output with your mouse ☺️.

Features

This project aims to rejuvenate Chris Kempson's original tool by incorporating some fresh features:

• Under active development
• Well-tested
• Simple to use
• Simpler to install
• Writes themes to stdout
• Written in uncomplicated JavaScript
• Works on Mac, Linux, and Windows

Installation

$ npm install --global base16-builder

_{Make sure to install Node.js before running the above command. We recommended that you install Node.js using nvm (the node version manager) or the pre-built installer for your platform. npm (the node package manager) is bundled and installed automatically with Node.js.}

Usage

$ base16-builder --help

  Usage:
    $ base16-builder <-s scheme> <-t template> <-b light|dark>
    $ base16-builder <-s scheme path> <-t template path>

  Options:
    -s, --scheme        Build theme using this color scheme
    -t, --template      Build theme using this template
    -b, --brightness    Build theme using this brightness
    -h, --help          Show this menu

  Commands:
    ls schemes      Opens an offline web page with a list of scheme names and their colors
    ls templates    Writes a list of available templates to the terminal

  Examples:
    $ base16-builder -s oceanicnext -t rxvt-unicode -b dark
    $ base16-builder --scheme oceanicnext --template rxvt-unicode --brightness dark
    $ base16-builder --scheme schemes/customScheme.yml --template templs/customTempl.ejs
    $ base16-builder ls schemes
    $ base16-builder ls templates

Build Status

Windows	Linux

Attribution

• The original base16-builder.
• Scheme and template contributors to the original base16-builder.
• Phis for the charming logo.

base16-builder's Issues

What do you think of the idea of moving to TypeScript?

Hello,

A quick question, I am asking myself. What do you think of a move to TypeScript?

• AFAIK, you use Atom who support TypeScript.
• You are coming from a C# background too, the TS's syntax should easier for both of us.
• TypeScript is widely use and a popular transpiler.
• TS support ES6 features with some ES7 feature like async/await.
• Since we can use it with plain, the migration will be smooth.
• TS works well with nodejs.
• A port will be simpler to do now.
• AFAIK, you dont have a project with it, base16-builder could be the first!

A stackoverflow talk about TypeScript.

Update the gif

Hello,

The demonstration gif is outdated. It would be nice to make another one.
Also, I think the picture could be a bit smaller.

Cheers,

Show a friendly error message when the given template or scheme does not exist

User stories:

• As a user, I am presented with a friendly error message when a theme I specify doesn't exist.
• As a user, I am presented with a friendly error message when a template I specify doesn't exist.

Example:

$ base16-builder -t i3wm -s wobble

$ fatal: Could not find a scheme called \"wobble\". It is likely that no template with this 
name exists. For a complete list of templates, see the database: https://goo.gl/ntnS1I

$ base16-builder -t wibble -s oceanicnext

$ fatal: Could not find a template called \"wibble\". It is likely that no template with this 
name exists. For a complete list of templates, see the database: https://goo.gl/fhm4Ct

Do we have a specific code guidelines to follow?

Hello,

Everything is in the title.
We have a .eslintrc but it is a bit light.

Thank you

Catch only specific error

Here we use a blanket catch statement.

Problem: It swallows all errors

Solution: Catch only specific errors

Configure ESLint to recognize ES2016 await feature

Possibly upload to AUR

Some people would like to install this tool via AUR instead of npm.

I'm not sure how viable this is because the tool has a dependency on nodejs.

Show success message when cli has finished executing

Add tests to ensure that success messages are green and error messages are red

In an attempt to eliminate the possibility of a trivial regression, tests should be included to verify that

• Success messages are output to the console with a green colour; and,
• error messages are output to the console with a red colour!

I haven't included these tests as I'm not yet sure how to go about testing this.

The module I use to colourize the output namely, Chalk, does so by emitting ANSI escape codes however, the terminal interprets these ANSI escape codes before I can evaluate them. Hm 😕.

Add support for VSCode

Hello,

Visual Studio Code support Textmate theme but it could be better with some adjustment.
I am looking for a better support. VSCode is shiped with an implementation of Solarized. It could be nice to use it as a bridge for the port.

Cheers,

Add -h alias for the --help argument

Consider a different name for the output folder

@cruor99 suggested that I change the name from output to base16/output or something similar.

Logo

Would anyone be interested in designing a vector logo for use in the readme.md?

In terms of design, I was thinking:

• Minimal
• 🔨 emoji?
• Should probably use at most 16 colors
• I like the hipster chalkboard look and feel but am flexible
• I especially like @sindresorhus's style e.g. his logos for chalk and got.

If you have a concept in mind, please bounce them off me before doing too much fine tuning. Aside from that I am pretty happy to give you free reign 👍.

Create a tool to reverse engine a template or a scheme

This issue is directly related to base16-builder. I would love to get a tool to create a template from a theme. Basically, it will replace colors with nunjucks string.

A maths metaphor would be: scheme + template = theme thank to base16-builder and with this tool we could do: theme - scheme = template or theme - template = scheme.

Add output directory to .gitignore

If I don't write it here, I'll forget...

Fix one failing test on master

Hi !

I found a failed test in master:

  27 passed  1 failed

  1. tests › buildTemplate returns correct result

  t.is(actual, expected)
       |       |        
       |       "\n    OceanicNext\n    https://github.com/voronianski/oceanic-next-color-scheme\n    1B2B34\n    343D46\n    4F5B66\n    65737E\n    A7ADBA\n    C0C5CE\n    CDD3DE\n    D8DEE9\n    EC5f67\n    F99157\n    FAC863\n    99C794\n    5FB3B3\n    6699CC\n    C594C5\n    AB7967\n  "
       "\n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n  "

  AssertionError: '\n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n    \n  ' === '\n    OceanicNext\n    https://github.com/voronianski/oceanic-next-color-scheme\n    1B2B34\n    343D46\n    4F5B66\n    65737E
    Test.fn (tests/tests.js:185:5)

npm ERR! Test failed.  See above for more details.

The branch master must never fail a test.

Target earlier versions of Node

Problem: At the moment, this module will only work on Node 5 due to the fact that it is transpiled using this Node 5 preset.

Solution: Use babel-preset-es2015 instead.

Document the template convention

Templates need to adhere to a certain convention before base16-builder can detect them.

Whilst I believe that most contributors will be able to deduce this convention by looking at the templates directory, it would also be beneficial to formally document the convention.

Seeing as how this information is most relevant to contributors, I think contributing.md would be a natural home for the so-called specification.

Write a script to import template names from https://github.com/chriskempson/base16-builder

Write a throwaway script that

1. Reads every template name from this folder

2. Generates a task list for every template name:

   

Once the script has finished running, we can create a new issue to track progress of #16.

Improve error messages

Add Toothpaste Scheme

https://github.com/imcatnoone/toothpaste

Would it be a good idea to use an inline logo?

Hello,

I think the logo take a lot of place.
What about an inline logo?

Something like this

{ # } BASE16-BUILDER

Where { # } is the logo.

Show a friendly error message when required arguments are not specified

User stories:

• As a user, I am presented with a friendly error message when I do not specify a template name (-t).
• As a user, I am presented with a friendly error message when I do not specify a scheme name (-s).

Examples:

$ base16-builder

$ fatal: You need to specify *BOTH* a template and a scheme name e.g.: 
base16-builder -t i3wm -s oceanicnext. If you are still having trouble, please refer to the
documentation for guidance: https://goo.gl/JwwX13

$ base16-builder -s oceanicnext

$ fatal: You need to specify *BOTH* a template and a scheme name e.g.: 
base16-builder -t i3wm -s oceanicnext. If you are still having trouble, please refer to the
documentation for guidance: https://goo.gl/JwwX13

$ base16-builder -t i3wm

$ fatal: You need to specify *BOTH* a template and a scheme name e.g.: 
base16-builder -t i3wm -s oceanicnext. If you are still having trouble, please refer to the
documentation for guidance: https://goo.gl/JwwX13

Make template and scheme names case-insensitive

Add support for group of template

Hello,

For now it could be done easily with bash script who are going to call base16-builder a bunch of time. I think it could be neat to handle this ourself something in this idea:

$ base16-builder -s gooey -t rxvt-unicode,i3wm,i3status,atom,vim

It could be handy when you want to change a complete theme.

If we add this, we are going to need to support an output directory. Afaik, pipes are strong but limited for this case.

I am perfectly ok with the current implementation, it allow to do a script who can take as parameter a dictionary with templateName as key and output as value. This script could be a new project.

Any thought?

Who is the author in a scheme file?

Hello,

In a scheme file we can find the name of an author. Who is he? He can be:

• The creator of the file.
• The creator of the scheme.

If I use the solarized theme, the author should be @altercation (scheme creator) or myself (file creator)?

To answer this, we could look at the use. Why should we add the author? What is the benefit of each one?

In another hand, could be use both?

For now, I think we should use the original author.

What do you think?

Point user in direction of help page when invalid arguments are specified

Inform the user to look at the --help page only.

Add Alfred template

Hello,

Alfred is an effective launcher for Mac. You can learn more about the project on its website.

Inspiration can be taken from my wox template see #59 or from a solarized implementation (1 2 3 4).

Cheers,

Create a simple web page that lists available schemes

Something like this but dynamically generated based on the schemes directory.

Ideally this will be hosted on GitHub pages for easy integration and free hosting.

Split base16-builder cli from core

Hello,

What would you think to split base16-builder in two projects. One for the core and one for the CLI. If someone, someday, want to create a GUI version or another tool. He could use the core part of base16-builer. In C#, i would ask for switching for one project to a group of projects (a PCL, a CLI, why not a wpf, etc).

Basically, can we add more modularity in base16-builder?

Improve readability of buildPath function

const templPath = await buildPath(templName, false);
const schemePath = await buildPath(schemeName, true);

Problem: It isn't really clear at a glance what the true or false arguments mean.

Solution:

1. Use an enum
2. Use named arguments
3. Create two discrete functions: buildTemplatePath and buildSchemePath that both call buildPath.

How can I run this project?

Edit

Because the subject change during the thread, I moved this issue to #15

Hello,

AFAIK, I cannot use base16-builder like this:

base16-builder -s db/schemes/railscasts.yml -t db/templates/i3wm.nunjucks

It would be nice to add path support.
Something like this (pseudocode)

if arg is path
    read it
elif arg is in db
   read it
else
   print usage

We could also use a specific flag but I find this idea more convenient.

Cheers,

Add tests to ensure that when an unexpected error is encountered, the correct error message is output

Make "-h" the default output

Hello,

When we run base16-builder without any arguments a "fatal" error is thrown:

fatal: You did not supply valid arguments. Run \'base16-builder -h\' for guidance.

I think it would be better to make the "-h" a default and to print it when no argument is given. It is the choice made by "git" or "npm" for example.

Cheers,

Adapt header comment in template

Some templates start with a header comment like this one:

<%=
bla bla
%>

We have to convert it.

Handle buildTheme exceptions

buildTheme can throw an error if the nunjucks template is invalid. This needs to be handled and a friendly error message should be shown to the user.

Add more color models to the template context

User story:

• As a developer, I am given each base16 color in the following format:
  • hex
  • hexbgr
  • dhex
  • rgb
  • srgb

Update help output to exclude i3wm

Add Wox template

Hello,

Wox is an effective launcher for Windows. You can learn more about the project on its repository.

Right now, I have the support for the dark and the light template (here with the solarized scheme):

I created them with wox's theme builder with inspiration from Alfred (1 2 3 4). I chose 0A as accent color but any accent color will fit (I found 0C really convenient too).

Convert DuoTone Themes to Base16 Schemes

Hello,

There are a lot of very nice theme for the Atom IDE. I would love to try them somewhere else. Can we think about a way to use them as scheme for base16-buider?

You can discover the concept here (by @simurai).

Is the path feature broken?

How the path feature works

It'll be impossible to tell if the user wanted a theme from the db or from her local path

Yes and it is a feature. The user must control waht he wants to do. He can choose.

Why?

Lets look inside the function buildPath():

async function buildPath(file, isScheme) {
    const exists = await fs.exists(file);
    if (exists) {
        return file;
    }
    return toRelativePath(isScheme ? `db/schemes/${file}.yml` : `db/templates/${file}.nunjucks`);
}

If the argument file is a path to a file, we use it. If the file is broken, it will be not our problem (at least for now. We should protect the user from himself, but this is a story for another PR).

If the argument file point to nothing, he should be a basic name of a template. Lets look in /db to find a matching one. We got a matched? Awesome! We use it. A file in db, cant be broken. It MUST be valid.

Wait... We reach here? There is a problem... an error somewhere... Lets throw a friendly message to inform the user, print a usage or something and end the script smoothly.

But there is a problem

What happened if the user do something like this?

$ base16-builder -s fooBar -t toto -l dark

We are looking if there is a file called toto if yes we use it, else we look into the db. That's all folks!

What if, we run the script inside /db? An user cant, but a contributor could. Ok, lets protect everybody. For this case it can be handy to change a bit buildPath(). I always said that we checked for an existsting file. This is wrong or at least, no so true. With fs.exists(), we check if a file or a directory exist, not only a file. To prevent this case we can replace fs.exists() with fs.lstat() and stats.isFile(). They is a nice question around this subject on Stack Overflow. Also, here is a link to the docs of fs.stats.

After the edit, we will have:

async function buildPath(file, isScheme) {
    const stats = await fs.lstat(file);
    if (stats.isFile()) {
        return file;
    }
    return toRelativePath(isScheme ? `db/schemes/${file}.yml` : `db/templates/${file}.nunjucks`);
}

What's next?

You said it! 😄

Add --template and --scheme flags

User stories:

• As a user, I want to write --scheme instead of s and --template instead of -t.

Invalid template error contains wrong url

It links to the schemes directory when it should link to the template directory.

Allow to use path to test custom theme

Hello,

AFAIK, I cannot use base16-builder like this:

base16-builder -s db/schemes/railscasts.yml -t db/templates/i3wm.nunjucks

It would be nice to add path support.
Something like this (pseudocode)

if arg is path
    read it
elif arg is in db
   read it
else
   print usage

We could also use a specific flag but I find this idea more convenient.

Cheers,

_Move from #14 _

Create a screencast showing how to use the tool

I will produce a short screencast for my YouTube channel, Code Cast

Port more templates

Do not auto-escape output

All you need to do is tell Nunjucks to not escape values. We don't care about XSS here 😏

Add more intuitive command-line arguments

User stories:

• As a user, I am able to specify 1, a scheme name, 2, a theme name, 3, luminosity and optionally, 4, a palette.
• As a user, if I do not specify luminosity or if I specify an invalid luminosity, I get an error.

Examples:

$ base16-builder -t i3wm -s gooey -l dark

$ set $base00 101218
$ set $base01 1f222d
$ set $base02 252936
....

$ base16-builder --template i3wm --scheme gooey --luminosity dark

$ set $base00 101218
$ set $base01 1f222d
$ set $base02 252936
....

$ base16-builder -t i3wm -s gooey -l light

$ fatal: Could not find a scheme called 'i3wm-light'
$ See 'base16-builder ls-schemes' for a list of available schemes.

$ base16-builder -t i3wm -s gooey -l dark -p 256

$ fatal: Could not find a scheme called 'i3wm-dark-256'
$ See 'base16-builder ls-schemes' for a list of available schemes.

$ base16-builder --template i3wm --scheme gooey --luminosity dark

$ fatal: You did not supply valid arguments. See 'base16-builder -h' for help/examples.

Add more detail to the manual

User stories:

• As a user, I am presented with a useful man page when I use the --help flag.

Examples:

base16-builder --help

Usage: 
  $ base16-builder [-s <scheme>] [-t <template>]

Options:
  -s, --scheme Build theme using this color scheme
  -t, --template Build theme using this template

Examples:
  $ base16-builder -s oceanicnext -t i3wm
  $ base16-builder --scheme oceanicnext --template i3wm

Should we use two separates flags to handle templates?

Presentation

To works, base16-builder need at least three arguments:

• a template
• a scheme
• a luminosity

We will not talk about luminosity here. Lets focus on template and scheme. Base16-builder ask them to provide a name or a path, so he can mix them and print a result on stdout. Since their logic are exactly equals, we are only going to talk about template. Sorry scheme, I wont miss you. Also, I will rename Base16-Builder "BB16" (acronym for "Builder-Base16"). Base16-builder is a long name and I am lazy.

BB16 gets the template like this:

• $> base16-builder -t solarized
• $> base16-builder -t /path/foo/bar/solarized.nunjucks

In the first command line, we give a name as argument to BB16. In the second command line, we give him a path. BB16 doesn't care. BB16 can eat both. Well, lets look in base16-builder belly. If we give him a path, he will used it, build a theme and print it to stdout. If we give BB16 a string who is not a path to a file, BB16 is going to interpret it as a name. BB16 thinks "How this argument is not a path so it must be a valid name!". He is going to look in his memory (the db folder) to find a template with a matching name. If he find one, he build himself a path to it like before. Then, he does his mix and print the result to stdout.

BB16 is polite. He will always check for input from the user before check in his memory.

If for some dark reasons BB16 cant find a path to a file or a name, he will print an error.

Problem

Ok. ok. What is the problem?

It is not really a problem. It is a decision to take. @alexbooker and I are not sure about what to do. This issue is here to explain the choice.

Now, we use the flag "-t,--template" to get both the name and the path and later, BB16 split them.

An alternative would be to use two flags: "--template" and "--template-path". The first one will handle name and the second one will handle path.

With two flags, we don't have to use a if to split the logic. The user with split it himself.

I think the current implementation is good enough. @alexbooker wonders whether the second is better or not.

Solution

Well, I am not going to give a solution. I will just explain my thought.

With the first implementation, the user doesn't have to do the job for us. He will have to choose the right flag for each case. If he wants to use BB16 like the old Base16-builder, he will have an error. To allow him to do this, he will have to change to this new flag "--template-path".

From the code, it might seem better. Less code to write because the user is going to choose between a name and a path (lets forget that this code already exists). We are going to create a new logic for arguments. To work, BB16 must have a template. So we are going to create a if to check if one flag is used, then we must block the other one.