Getting Started

This guide will walk you through getting your first Shayu site set up.
You can also look at the code for this site and use that as your starting point.

1. Prerequisites

You will need Node.js and a package manager for it like npm or yarn. The instructions below use Yarn but should be easy to adapt

yarn init
yarn add shayu react postcss-import

Note:

The postcss plugins you have to install will depend on what you want to do in your stylesheet(s), postcss.parts has a list.
currently postcss-import is required if you want to have multiple stylesheets, as anything ending in .css except entryFile will be ignored.

Future:

A more advanced asset transformation is planned, which will give a lot more flexibility in this regard.

You can find more information about this on the Roadmap#better-assets

2. index.js

Shayu needs to be called with a config object, and the easiest way to do that is to populate your index.js as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
"use strict";

const shayu = require("shayu");

const config = {
    basePath: __dirname, // easy way to get the path where this index.js is in, all directories will be based from here
    assets: {
        postcssModules: [
            require("postcss-import")(),
            require('postcss-mixins')(),
            require("postcss-nested")(),
            require('postcss-simple-vars')(),
            require('postcss-color-function')(),
            require('autoprefixer')(),
            require('postcss-math')()
        ]
    },
    HTMLcomponents: {
        code: './components/code'
    },
    livereload: 'env'
};

shayu(config);

3. Configuration

basePath is really the only required option, in which case Shayu will pick the following defaults for you:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
let defaultConfig = {
    assets: {
        cssEntry: 'style.css',
        postcssModules: []
    },
    defaultMeta: {
        title: "Untitled Page",
        layout: "./default"
    },
    HTMLcomponents: {},
    directories: arrToObj(["pages", "assets", "build", "layouts", "components"]), // results in {pages: "pages", assets: "assets"} etc.
    livereload: false,
    ports: {
        http: 8080,
        livereload: 35729
    }
};

4. Directory structure

Next up there's 2 important files we need: the stylesheet, and the default layout component.

Future:

Currently Shayu will give quite cryptic errors if these are missing, this is to be fixed soon(tm)

You can find more information about this on the Roadmap#cryptic-errors

These reside in pages/style.css and layouts/default.jsx with the default config. The stylesheet can just be an empty file, whereas the default stylesheet needs to export a React component, taking the following props:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
"use strict";

const React = require('react');

function Layout({mdxContent, meta, pageContext}) {
    return (
        <html lang="en">
        <head>
            <meta charSet="UTF-8"/>
            <meta name="viewport" content="width=device-width"/>
            <meta name="description" content={meta.excerpt ? meta.excerpt : ""}/>
            <link rel="stylesheet" href="/assets/bundle.css"/>
            <title>{meta.title}</title>
        </head>
        <body>
            <h1>{meta.title}</h1>
            {mdxContent}
            <span>This site was made with <a href="https://shayu.it">shayu</a></span>
        </body>
        </html>
    );
}

module.exports = Layout;

This component will be used to render your pages, unless they specify a different layout to use in their meta.

5. Pages

Now we can get to the most important part of your site; actually writing the content.
Currently Shayu only supports files written in MDX: a combination of Markdown and JSX components.
This allows you to write with the simplicity of Markdown, while including reusable JSX components for added functionality. You can also override default markdown elements, such as code blocks, to add extra functionality like syntax highlighting.

Future:

Support is planned for pages that only exported a JSX component, without parsing any MDX

You can find more information about this on the Roadmap#jsx-pages

5.1. Routing

Shayu will only consider files ending with .mdx in your pages directory, render those, and render them to your build directory according to the following routing logic:

InputOutput
page/index.mdxbuild/index.html
page/getting-started.mdxbuild/getting-started/index.html
page/projects/index.mdxbuild/projects/index.html

Warning:

This can result in an output conflict, like when you have both projects.mdx and projects/index.mdx
Shayu will complain and error out.

5.2. Meta

Your page can export a meta object, to override the keys set in your defaultMeta config, and provide page specific info.
It will be merged, so you don't have to define all keys;

export const meta = {
    title: "Getting Started",
    customProp: "I can define anything!"
}

These can then be used inside your layout, or when enumerated by components using pageContext.getOtherPageMetas(), to provide things like navigation menus and project listings

5.3. Components

To use a component, you first have to import it. If you forget this, the MDX parser will default to a <div>, and output a warning to the console: Component X was not imported, exported, or provided by MDXProvider as global scope 

import Card from "./card"
# this is a header

<Card>This will be rendered inside my custom Card component</Card>
This site was made with shayu