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

• NodeJS
• Handlebars
• Tailwind CSS

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.

1. 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.
2. Change into the theme directory
3. 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.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Copyright © 2021 by Pinpoint Software, Inc. Distributed under the MIT License. See LICENSE for more information.

Contact

If you need any assistance at all, please contact [email protected]. You can also contact us up in the Changelog app using the chat bubble.

Jeff Haynie - @jhaynie - [email protected]

Project Link: https://github.com/pinpt/changelog