Home

Awesome

nextein

A static site generator based in Next.js

GitHub Workflow Status npm

Site | Documentation | Guides

What is it?

nextein is a wrapper around next.js that allows you to write static sites using markdown and react.

Requirements

NodeJS v10.x+ is required to run nextein commands.

Starter Kit

If you want to jump into a starter project check nextein-starter

Getting Started

There are a few steps you have to follow to get your site up and running with nextein

Documentation

fetcher

Use fetcher to retrieve the posts and data from your markdown files.

The getPostsFilterBy and getDataFilterBy methods in fetcher allows to pass filter functions. For instance, we can use inCategory filter to retrieve posts in a given category:

import { getPostsFilterBy } from 'nextein/fetcher'
import { inCategory } from 'nextein/filters'

//...
const blog = await getPostsFilterBy(InCategory('blog'))

The getData and getDataFilterBy will retrieve only the metadata generated for entries instead of the entire post.

The fetcher method is a convenient way to define a filter and then use the getPosts and getData with a filter applied.

import fetcher from 'nextein/fetcher'
import { inCategory } from 'nextein/filters'

//...
const { getPosts } = fetcher(InCategory('blog'))


//...
const blog = await getPosts()

You can use Dynamic Routes and static generator functions (getStaticProps and getStaticPaths) with fetcher methods.

Example for a [name].js dynamic route

import fetcher from 'nextein/fetcher'

const { getData, getPost } = fetcher(/* filter */)

export async function getStaticPaths () {
  const data = await getData()
  return {
    paths: data.map(({ name }) => ({ params: { name } })),
    fallback: false
  }
}

export async function getStaticProps ({ params }) {
  const post = await getPost(params)
  return { props: { post } }
}

export default function Post ({ post }) {
  //...
}

Example for a [[...name]].js dynamic route:

import fetcher from 'nextein/fetcher'
import { inCategory } from 'nextein/filters'

const { getData, getPosts, getPost } = fetcher(inCategory('guides'))

export async function getStaticPaths () {
  const data = await getData()
  return {
    paths: [{ params: { name: [] } },
      ...data.map(({ name }) => ({ params: { name: [name] } }))
    ],
    fallback: false
  }
}

export async function getStaticProps ({ params }) {
  const posts = await getPosts()
  const post = await getPost(params) // This can be null if not matching `...name`
  return { props: { posts, post } }
}

export default function Guides ({ posts, post }) {
  //...
}

inCategory(category, options)

Filter function to be applied to posts to retrieve posts in a given category.

Categories are resolved by the folder structure by default. This means that a post located at posts/categoryA/subOne will have a category categoryA/subOne unless you specify the category name in frontmatter.

import { getPosts } from 'nextein/fetcher'
import { inCategory } from 'nextein/filters'

//...

const posts = await getPosts()
const homePosts = posts.filter(inCategory('home'))

If you want to retrieve all posts under a certain category, let's say categoryA which will include all those under subOne, use the options includeSubCategories: true.

import { inCategory } from 'nextein/filters'

const categoryAPosts = posts
  .filter(inCategory('categoryA', { includeSubCategories: true }))

Content

Component to render a post object. This component receives the content from the post as a property. Use the excerpt property to only render the first paragraph (this is useful when rendering a list of posts).


import Content from 'nextein/content'

//...

export default function PostPage ({ post }) {
  return <Content {...post} />
}

Using renderers to change/style the <p> tag


const Paragraph = ({ children }) => (<p style={{padding:10, background: 'silver'}}> { children } </p> )

// Then in your render method ...

  <Content
    {...post} 
    renderers={{
      p: Paragraph 
    }}
  />

post


{ data, content } = post

frontmatter

There are only a few defined properties in the frontmatter metadata that is used by nextein

---
category: categoryOne
date: 2017-06-23

---

Post Content...

withNextein

A wrapper configuration function to be applied into the next.config.js. It provides a way to add your own next.js config along with nextein internal next.js config.

next.config.js

const { withNextein } = require('nextein/config')

module.exports = withNextein({
  // Your own next.js config here
})

Plugins

You can also define nextein plugins using the withNextein configuration:

const { withNextein } = require('nextein/config')

module.exports = withNextein({
  nextein: {
    plugins: [
      //your nextein plugins here
    ]
  }
  // Your own next.js config here
})

The nextein.plugins configuration accepts an array of plugins with the following formats:

The plugin name should be a pre-installed plugin (nextein-plugin-markdown) , or a local file (./myplugins/my-awesome-plugin)

Default Plugins

The default configuration includes:

plugins: [
  ['nextein-plugin-source-fs', { path: 'posts', data: { page: 'post' } }],
  'nextein-plugin-markdown',
  'nextein-plugin-filter-unpublished'
]

nextein-plugin-source-fs

Read files from file system.

Options:

nextein-plugin-markdown

Render markdown files.

Options:

nextein-plugin-filter-unpublished

Filter posts by using a property to prevent draft / unpublished entries to be displayed.

Options:

Writing Plugins

You can write your own plugins. There are basically 2 different types (source and transforms). Source plugins will be called to generate the posts entries and then the transform plugins will receive those entries and can modify, filter, append, or transform in anyway the posts list.

See plugins & lifecyle design document.