Quick Start Guide

There are several ways to use poko. We will try to get you started as fast as possible then you can improve your workflow according to your needs later.

If you feel like watching instead of reading, the first 30 minutes explain how to setup your website.

Accounts

To provide a 100% free and open source experience while still providing a good user experience, poko relies on a few free services.

• A Content Management System (CMS) to edit your content. Currently only Notion is supported.

• A static hosting platform to host your website. There are many free options and you can even self-host if you want but that is a topic for another time. Netlify and Vercel are probably the most popular options. We prefer Cloudflare Pages as their free plan seems more generous.

• A source code repository of your own. This is needed because hosting platforms can fetch code on your behalf but only in a repository you own. Gitlab is probably better in terms of values. Github is more popular.

Notion

1. Create a free account at https://www.notion.so/

2. Duplicate this simple template (upper right corner button)

3. Create you Notion API key

   1. Go to https://www.notion.com/my-integrations.

   2. Click the "+ New integration" button.

   3. Give your integration a name, for example "Website" (if you'll only have one).

   4. Select the workspace where you want to install this integration. Must be the one where you copied the template at step 2.

   5. Select the capabilities that your integration will have. For the current state of poko, you can select "Internal integration", "Read content" (no need for "Update" or "Insert") and "No user information".

   6. Click "Submit" to create the integration.

   7. Copy the "Internal Integration Token" on the next page and save it somewhere secure, e.g. a password manager.

   8. For complete instruction, refer to Notion's docs.

4. "Invite" your integration in the root Notion page

   1. Go back to the root page of the template you copied in your space at step 2,

   2. Click "share" in the top right corner.

   3. Click in the "Invite" box and select the integration you just created.

   4. For complete instruction, refer to Notion's docs.

5. Get ready for liftoff! 🚀

The "one-click" setup with Netlify or Vercel

1. Create a Github account.

2. Create a Netlify or Vercel account.

3. Click on the appropriate button (green for Netlify, blue for Vercel)

   📌 Netlify "easy deploy" is not working properly at the moment.

   

4. Follow the instructions

   • Production branch: Choose the prod branch if you want the latest updates

   • Environment variables:

     • NOTION_TOKEN is the API key you saved from your Notion integration.

     • SITE is the public URL of your future website. It is ok to set this up with a temporary value but you should change it as soon as you decide what your URL will be. It does not have to be your own domain. A Netlify or Vercel URL is fine.

     • NOTION_ROOT_ID is optional. You need this if you use the same Notion integration for multiple websites.

5. Visit your new website with the link provided by your service of choice. 😁

Note: Visit Netlify's docs or Vercel's docs to know more about managing your hosting.

What next?

Templates

We will create more templates and examples for you to duplicate, copy/paste or get inspiration.

This is what we have for now:

Community

If you like poko, come and share what you have been pushing online, give us a star on Github (top right corner), ask questions, share ideas, invite friends to give poko a spin.

Github Discussions are currently the best place to discuss anything poko. Don't be shy!

Updates

This is an Alpha release. It means that the project is merely taking shape. Anything can change or break without much notice.

Updates are pushed to github. We'll try to bundle updates and make proper announcements through Github Discussions. Currently, the prod branch is where new features and fixes are pushed immediately.

If you have been following this Quick Start Guide or have forked the Github repository on your own, you can update your version of poko through Github. Look for the "Fetch upstream" button just underneath the green "< > Code" button. It should allow you to update your version of the code according to the original repository.

Extending poko

There are a lot of possibilities to extend poko: components, full themes, functionality, ...

If you are a developer, a designer or an enthusiastic geek and you want to contribute some time to this project, feel free to start a discussion.