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.
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)
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
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:
Input | Output |
---|---|
page/index.mdx | build/index.html |
page/getting-started.mdx | build/getting-started/index.html |
page/projects/index.mdx | build/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>