Ambercat

Stupidly simple static site generator based on Vue.js and Tailwind CSS (Demo here).

How to Install

Init your npm project first:

npm init  && cd 

then add this repo as local dependency:

npm install ambercat --save

then run this command to init blog project:

npx ambercat init

Run Dev Server

To start dev server, run:

npx ambercat dev

For local development, the homepage will be accessible on https://localhost:3000.

If you want to preview your blog on your device, you can use the public url which will be printed on your command line. Make sure that your device and your computer are connected to the same network.

Every changes to theme and posts will be triggering browser reload across devices.

Add a Post

To add a post, run:

npx ambercat post 

By default, the command will create YYYY-MM-DD-your-post-title/index.md file in your src/posts directory. The date prefix will be used to determine the post date.

Every index.md file will be generated into /your-post-title.html path.

Build Static Site

To build static site, run:

npx ambercat build

Static site files will be generated in your build directory. You can upload them to Github Pages or your chosen web service.

Ambercat doesn't provide you with any kind of deployment flow so you need to configure it yourself.

Customize Your Blog UI

All of UI code are stored inside of src directory. Pay attention that there are two kind of entry files:

1. entry-client.js. This file will be used to build js file to be served along with your static site.
2. entry-server.js. This file will be used to generate the static site. In most cases, you don't need to work with this file.

HomePage

The HomePage.vue component will accept data object with properties below:

The data.posts contains an array of the most recent posts with these properties:

PostPage

The PostPage.vue component will accept these properties:

Add a new static page

Create your custom static page component on src/components directory, then edit src/router.js.

// src/router.js
...
  routes: [
    {
      path: '/',
      component: Homepage,
    },
    {
      path: '/index.html',
      component: Homepage,
    },
    {
      path: '/404.html',
      component: FourOhFourPage,
    },
    {
      // .html extension is important
      path: '/your-custom-static-page.html',
      component: YourCustomStaticPage,
    },
  ],
...

On your ambercat.config.js, register new static pages by adding it into staticPages property.

// ambercat.config.js

module.exports = {
  ...
  staticPages: [
    { filename: 'index', title: 'Ambercat', description: '....', numOfPosts: 5 },
    { filename: '404', title: '404' },
    { filename: 'your-custom-static-page', title: 'Your custom static page', numOfPosts: 'all' },
  ],
  ...
};

The title values will be used to set title page. The filename should be matched with the route you just registered on src/router.js. The optional description value will be used for meta description on your page. The value of numOfPosts can be an integer or string 'all' if you want to make data.posts accessible on your static page component.

Customize tailwind.js

The default configurations from the original tailwind init have mostly been edited following to the default theme design. However, the edited values are left commented so you can easily enable them later. Refer to https://tailwindcss.com/docs/configuration for further guideline.

Enable Syntax Highlighter

Syntax highlighter is disabled by default. To enable it, register languages on syntaxLanguages key on ambercat.config.js. Refer to this page for supported language.

// ambercat.config.js

module.exports = {
  // ..
  syntaxLanguages: ['html', 'css', 'javascript'],
};

Configuration

All of project configurations are stored in ambercat.config.js file and should be self explanatory. Below are descriptions for advanced usage.

Webpack

You can add your webpack config by using configureWebpack hook. The returned object will be merged with internal webpack configuration. Use isServer flag to avoid misconfiguration.

This hook should always return an object if you decide to use it. If you don't need to add anything, simply exclude it from your configuration.

Asset Injector

Sometimes you want to add extra scripts like analytics or css tags on template. However, it is forbidden to add it via Vue.js component. By its nature, Vue.js will reject tags with side-effects like `