Write Site
Hikaru won't create pages and posts for you, however, they have a readable format and you can create them by yourself.
Example file
A page usually is a Markdown file which has a YAML front matter and a Markdown content like this:
---
title: Your page title
# Should in ISO 8601 date time format, local timezone will be used if timezone is omitted.
created: 2018-08-08T09:27:00
# If you updated your content, you can use this key.
#updated: 2019-01-01T19:07:00
layout: post
---
Text before more will become excerpt.
<!--more-->
# A Title
Content.
## Another Title
Content.
Front matter
Front matter is written in YAML, which is in the head of file and between ---\n
and \n---\n
. But more than 3 -
and \r\n
are also acceptable. It is used to present metadata of a page. By default Hikaru needs following 3 option:
title
Your page's title, NOT URL, your page's URL depends on your page's filename.
created
Your page's writing date. Should in ISO 8601 date time format, local timezone will be used if timezone is omitted.
updated
Your page's modifying date. Should in ISO 8601 date time format, local timezone will be used if timezone is omitted.
draft
If you've not finished your post, you can set draft: true
, so it will only visible when using hikaru serve
but not hikaru build
.
layout
Your page's layout, which depends on which template of your theme will be used to render your page. Typically you need following layout pages:
index
This usually is a page that theme will put all posts with its excerpt inside.
archives
This usually is a page that theme will put all posts without its excerpt inside.
categories
This usually is a page that theme will create a nested list of all categories.
tags
This usually is a page that theme will create a tag cloud of all tags.
Useful Rules
Hikaru will resolve anchors (<a>
) and images (<img>
) in your posts and try to convert relative path into full path, so even if your post content is on some RSS hubs (most RSS hubs just simply join your domain and link), it still works properly.
Links match the following rules will be considered as already full path and won't be resolved:
- Already has an origin that differs from your site.
- Starts with
/
or//
. - Have URL protocol, like
https:
ordata:
.
Hikaru will resolve content of headers (<h1>
, <h2>
, <h3>
, <h4>
, <h5>
, <h6>
) to generate a readable ID for them (compared with most Markdown renderer), and make a TOC
object for theme.
ID generating follows those rules:
- Chars not supported by scrollspy will be removed (space,
\t
,\n
,\r
,(
,)
,[
,]
,{
,}
,<
,>
,.
,,
,!
,@
,#
,$
,%
,^
,&
,*
,=
,|
,`
,'
,/
,?
,~
). - If the same ID has been generated,
-n
will be append to ID,n
is how many times it has been generated, for example, if we haveabc
,abc
andabc-1
as input, we will getabc
,abc-1
andabc-1-1
as output.