Letterpad ·
Letterpad is an open-source and a high performant publishing engine for blogs with a state-of-the-art technology. It uses React, Graphql, Express and Sequelize ORM. It is getting closer to releasing v1.0. Few of the core features are listed below:
- Server side rendering
- Multi author support
- Comments (Disqus integration)
- Google Analytics
- Theme support
- Multi-level navigation
- Image optimizer
- React with styled-components for styling
- GraphQL for json API
- Roles - Admin, Reviewer, Author, Reader
- Markdown and RichText editor
- Search Engine Optimised
- Multi-language support with react-i18next (currently en, fr and pl)
Demo
To check letterpad in action, check out this Demo Site. You can visit the Admin Panel and login with
Email: demo@demo.com
Password: demo
A verbose documentation can be found at https://letterpad.app/docs.
Letterpad is an open source project, licensed under MIT. It runs ridiculously fast.
The API of letterpad exchanges information in json and you have full control over what data to get, set and display. You can build entire publishing apps on top of it, and completely customise the reader experience.
Installation
There are three steps to install letterpad in the development environment.
- Open a terminal and clone the project:
git clone https://github.com/letterpad/letterpad.git
cd letterpad
-
Make a copy of
sample.env
and name it.env
. Open it and changeSECRET_KEY
to a random string to secure your app. Then add your SMTP credentials so email can be sent. Change the database options accordingly. By default, letterpad usessqlite
. -
Install dependencies and run (use yarn to install dependencies):
NODE_ENV=dev yarn install
theme=hugo yarn dev
NODE_ENV=dev yarn install
is going to install all the dependencies, seed the database, prepare a build and welcome you to letterpad.
Now visit http://localhost:4040 and checkout the welcome page.
To visit the admin panel, visit http://localhost:4040/admin and login with
Email: demo@demo.com
PAssword: demo
Creating a build for production
The below command will create a build for the api
, the admin dashboard
and the theme
. You will have to specify which theme you want to build.
theme=hugo yarn build
- This will create a folder called
apiBuild
which will contain all contents of theapi
folder in ES5. - All the admin dashboard specific bundle will be in
admin/public/dist
folder. - All the theme specific bundles will be in
client/hugo/public/dist
folder. - The vendor bundles are common between admin and client. So they will be in
public/js
folder.
How it works ?
Letterpad needs two servers to run your blog. One server runs Graphql API and the other server runs the Letterpad Engine. However with little modification, you can combine this to use one server.
Themes have their own seperate repository. While doing yarn install
, the default theme hugo
is fetched as a dependency during the installation. If the theme already exist, this step will be ignored.
Every theme should contain the below config file. This will have some metadata about your theme.
{
"name": "Hugo",
"short_name: "hugo",
"description":
"A theme for writing classic blogs. Seo optimised, spa, disqus integrtion",
"author": "Redsnow",
"thumbnail": "/images/thumbnail.png"
}
This thumbnail path should exist inside the public folder of your theme
Read more about how to create a theme in the documention site.
Admin Authentication
Apollo Client is responsible to exchange data with graphql. After the users logs in to admin panel, a new token is created with the below information:
email: "EMAIL" id: "USER_ID" role: "ROLE_NAME" permissions: "PERMISSIONS" name: "AUTHOR_FNAME" expiresIn: "30d" // "1d";SECRET // from .env file expiresIn
This token is then saved in localStorage. For every secured route in admin panel, a new token is issued and the previous token in localStorage is updated.
You can check the code of this here: shared/apolloClient.js
.
And you can check the code at the route level here - admin/containers/Secured.js
Graphql API
The graphql api code (ES6) for development is in the api
folder. After the build, the folder apiBuild
is created which contains all api code in ES5. This is used in production.
The api folder has well defined schemas in the schema
folder and its resolvers in the resolvers
folder. If you wish to make any change in the database label, then you should create a migration file. To create a migration file, enter this command:
yarn sequelize migration:generate --name specify-a-name-for-this-migration
//eg.
yarn sequelize migration:generate --name addGoogleAnalyticsField
The above migration will be created in `api/housekeeper/migrations/xxxxxxxx-addGoogleAnalyticsField.js
In order to run the migrations, enter the below command.
yarn sequelize db:migrate
You can play around with the Graphql API locally on http://localhost:3030/graphql
Translations
Letterpad uses react-18next library to handle translations. To add, edit or delete trannslation objects, you can use the below commands:
usage: yarn [operation] [options] [key=value || key]
operation (Required):
-a, --add Add key value pair to all files
-s, --set Set value of an existing key in all files
-d, --del Delete key from all files
--sync Sync all files with en.json
options (Optional)
-en Operation only on this file
-fr Operation only on this file
-pl Operation only on this file
# Adds the translated value, only in en.json and for others leave it blank. yarn translate --add save="Save" # Set the translated value only in en.json and for others, set the value to empty string. yarn translate --set oldKey="New Value" # sets a translation object in one file yarn translate --set -en oldKey="New Value" # deletes a translation object from all files yarn translate --del save # deletes a translation object from one file yarn translate --del -en tags.title # sync all files with en.json yarn translate --sync
VSCode setup
Extensions: Prettier, postcss-syntax, GraphQL, ESLint, DotENV, Babel ES6/ES7
npm i -g babel-eslint
For Prettier, it is recommended to add to the editor's settings.json
to run on save.
"editor.formatOnSave": true
Seeding
If you want to seed the database with sample data, run the below command:
// you should have babel-cli installed. Its good to have this package installed globally.
yarn seed
Addition Links:
Contribute
Letterpad is in its early stages and requires support to move ahead. You can contribute through various ways like testing, ideas, recommendations, fixing bugs, documentation, logo design, assets, etc. You can join the slack channel (letterpad.slack.com) for discussions. Thanks.
Contributors
This project exists thanks to all the people who contribute. [Contribute].
Backers
Thank you to all our backers! 🙏 [Become a backer]
Sponsors
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]
License
Letterpad is released under the MIT License.