@pinpt/changelog NPM

About The Project

pinpoint.com is an app built for fast moving product teams to help them manage the way they communicate with their end users. This tool is used by Pinpoint to generate static sites published by pinpoint.com as well as for development on new themes for your own site.

Built With

Getting Started

To get up and running follow these simple steps.

Prerequisites

You'll need to install a minimum of NodeJS v14 or later to use this project.

You can either install it globally or use npx:

npm install @pinpt/changelog -g

You can also use npx:

npx @pinpt/changelog

You can run the program without arguments or use the --help flag to get more details for each command.

For example, to get general help:

changelog --help

To get a command specific help:

changelog create --help

NOTE: you do not need to fork this repo directly unless you want to make a change to the basic template or the CLI tool itself.

Create a new theme

To develop a new theme, you need to first generate a template project.

Create a theme
```
npx @pinpt/changelog create --site SLUG --name THEME
```
Replace SLUG with either your site slug or the hostname. Replace THEME with the name of your theme. The THEME is optional and if not provided defaults to the same name as your site. For more options, use --help.
Change into the theme directory
Install NPM packages
```
npm install
```
This is optional. If you have installed the changelog npm globally, it will pick up that too.

Building your theme

Once you have installed a theme or cloned a repo with an existing theme, you will want to build your theme. Building your theme converts your theme template files into their equivalent generated posts for each of your changelogs.

npm run build

By default, this will generate your theme into $PWD/dist. You can get further options by using the --help option.

Developing your theme

To develop a theme, you want to make changes to your theme.css or override one of the template partial files (named with .hbs extension). The templates are built in HTML and use Handlebars for templating. You can override a specific partial by creating a new file named using the pattern [SCOPE]_[NAME].hbs such as web_footer.hbs which will override the base footer for the web scope. We currently have two scopes (web and email). The email scope is for modifying the email. You can create a new email template by creating a file named email.html in your theme. However, we highly recommend you instead create an partial override instead as the base email template has been tested to work in a majority of the email clients in the market.

To run the dev server:

npm run dev

This will start a local dev server on port 4444 running your generated site. On startup, it will build your entire site and watch for changes to your theme directory and rebuild as you make changes.

Packaging your theme

Once you're ready to deploy your theme, you'll need to package your theme and then upload it to the Theme area in Settings.

To package:

npm run package

This will create a theme.zip file in your $PWD/dist folder by default.

WARNING: make sure you check-in your changes to GitHub or otherwise back them up. If you delete or update the theme in the app, we might be able recover your files or changes but you will need to contact us to provide assistance since this is a manual process.

Handlebars

We support the following additional helper functions in handlebars:

formatNumber - format a number
compactInteger - return a compact representation of an integer (such as 5K)
boundedNumber - return a bounded number value
fileSize - return a human representation of a file size (such as 5KB)
truncate - truncate a string to a max length
truncateWords - truncate a set of words to a max count
capitalize - capitalize a string
titleCase - title case a string
pathname - return the pathname part of string that is a URL
gt - a > block expression
lt - a < block expression
gte - a >= block expression
lte - a <= block expression
first - return the first item in an array
last - return the last item in an array
empty - returns true if the array is empty
after - returns one or more items from an array (similar to splice)
pick - pull out an item from an array at a specific index
include - include another file
fontawesome-icon - generate a fontawesome icon (only available on web scope)
friendly-date - generate a friendly date
iso_date - generate an ISO date from a number
cover_image_url - return the url to the cover image or empty string if not provided
author - return a formatted list of authors
twitter_handle - return the twitter handle from a twitter url

Configuration

You can disable certain features from the base template by modifying the changelog.[SCOPE].features fields in package.json. The following are the current flags:

For the web scope:

themeSwitcher: if you want to enable dark/light mode theme switching
search: if you want to enable site search
tags: if you want to enable displaying tags on a post
tagFilter: if you want to enable filtering by tags
authors: if you want to enable showing the author(s) on the post
claps: if you want to display the clap count for a post
pageviews: if you want to display the page view count for a post
highfive: if you want to enable "highfive" (which results in claps) for posts
social: if you want enable the social buttons in the footer (must be configured in Settings/Theme in the app)

Versioning

You can control the version of your site and tie it to a specific version by changing the changelog.version field in package.json. This must be either latest or a valid semantic version rule. If you use latest, we will build your site with the latest verion of the builder (this repo) as they are published. If you set the value to ^2.0.0, for example, it will only support the 2.x version of the builder. We strongly recommend using latest unless you have made significant changes to your project which could be broken as we upgrade the base theme.

Assets

You can add the following assets to your theme and they will automatically be copied to the /static folder and you can reference them such as /static/NAME where NAME is the asset name in your template.

The following file extensions are allowed:

gif
png
jpg or jpeg
webp
mov
mp3
mp4
webm
svg

Assets in this folder must be immutable so make sure you change the name or add a version to the filename if you change them. Assets in this folder will be served with a long-term Cache-Control HTTP header.

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.