Quick Start

Scaffolding Your First Karbon Project

To get started with Karbon, execute the below command in your terminal:

npm init @storipress/karbon
# or
yarn create @storipress/karbon

Manually Installation

1. Install Karbon via npm or yarn.

npm install @storipress/karbon
# or
yarn add @storipress/karbon

2. Add Karbon to your modules section in your nuxt.config.js

export default defineNuxtConfig({
	modules: ['@storipress/karbon', '@nuxtjs/tailwindcss']
})

💡
Karbon has already set up the relevant template paths for Tailwind, but due to module loading order issues, in the nuxt.config.js settings, please put @storipress/karbon before @nuxtjs/tailwindcss, or add the paths to all of your template files in your tailwind.config.js file.

// tailwind.config.js
module.exports = {
  content: [
		'./templates/article-layouts/**/*.{vue,js,ts,jsx,tsx}',
		'./templates/editor-blocks/**/*.{vue,js,ts,jsx,tsx}',
		'./templates/resources/**/*.{vue,js,ts,jsx,tsx}',
	],
}

Connect to your publication

Karbon requires that it be connected to your publication via the setup of an .env file. Copy the .env.example file to .env and fill in the following information:

NUXT_KARBON_API_TOKEN=YOUR_NEWSTAND_API_TOKEN_HERE
NUXT_KARBON_SEARCH_KEY=YOUR_SEARCH_KEY_HERE
NUXT_KARBON_CLIENT_ID=YOUR_CLIENT_ID_HERE

The required tokens and client ID can be found in Storipress by going to Publication Settings → Newstand API.

Deploy

1. Deploy your custom publication style(s)

After successfully deploying, you can use your custom layout and blocks in Storipress’ document editor.

Directory Structure

The default structure of a Karbon application includes the following folders which contain corresponding resource files.

Directories

The resources directory

Karbon uses the /templates/resources/ directory to automatically generate article, author, desk, and tag pages, you can customise the styles or remove unwanted pages.

// /templates/resources/article.vue
<script lang="ts" setup>
const article = setupPage({ type: 'article' })
</script>

<template>
	<ul>
    <li>title: {{ article.title }}</li>
    <li>layout: {{ article.layout }}</li>
  </ul>
</template>

The /templates/resources/article.vue file will be mapped to the /posts route of your publication. This is the default configuration. Discover more in Resources.

The article-layouts directory

Developers can customise the design of their publication articles and utilise multiple designs. These designs can be uploaded using the Karbon CLI and used in the Storipress editor.

Layouts are placed in the /templates/article-layouts/ directory, discover more on the Article Layout page.

The editor-blocks directory

Developers can customise the style the style of editor blocks which can be uploaded using the Karbon CLI and used in the Storipress editor.

// /templates/editor-blocks

Blocks are placed in the /templates/editor-blocks/ directory. Learn more in the Editor Blocks.