160 lines
8.3 KiB
Markdown
160 lines
8.3 KiB
Markdown
|
# Command line syntax
|
||
|
|
|
||
|
|
Hablo provides several arguments that can be used at runtime. You can view them by running
|
||
|
|
|
||
|
|
```bash
|
||
|
|
hablo --help
|
||
|
|
```
|
||
|
|
|
||
|
|
in a terminal but here's a more complete description.
|
||
|
|
|
||
|
|
## Optional argument
|
||
|
|
|
||
|
|
Hablo expects only one argument which is optional, the root directory of the blog. It is convenient to run hablo from within the root directory of your blog because many options take a relative path so the default value is `.`.
|
||
|
|
|
||
|
|
## Article path
|
||
|
|
|
||
|
|
`-a, --articles`
|
||
|
|
|
||
|
|
Remember when you generated your very first hablo blog ? I said articles went to a directory named `articles` but it could be named differently. This is the option that allows you to do that.
|
||
|
|
|
||
|
|
For instance, assume that you're gonna make a blog about turtles. Each post is going to be a detailed presentation of all you know about one particular species of turtles, so it makes sense to put all your markdown files in a directory called «turtles». Well simply add this option when you call `hablo`.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
hablo --articles turtles
|
||
|
|
```
|
||
|
|
|
||
|
|
Note that this option is relative to the root of your blog so even if you hadn't run this command from within your blog you would have typed
|
||
|
|
|
||
|
|
```bash
|
||
|
|
hablo --articles turtles /path/to/your/blog
|
||
|
|
```
|
||
|
|
|
||
|
|
See ? It was still `turtles` and not ~~`/path/to/your/blog/turtles`~~.
|
||
|
|
|
||
|
|
## Banner
|
||
|
|
|
||
|
|
`-b, --banner`
|
||
|
|
|
||
|
|
By default hablo will generate a very simple banner for your blog with its name as a link to the main page and this option is the way to replace it with some arbitrary HTML.
|
||
|
|
|
||
|
|
The banner is processed when your blog is generated so it's not relative to the root of your blog, the banner file can totally be outside of your blog structure.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
hablo --banner /my/set/of/banner/turtles.html /path/to/your/blog
|
||
|
|
```
|
||
|
|
|
||
|
|
## Card image
|
||
|
|
|
||
|
|
`-c, --card-image`
|
||
|
|
|
||
|
|
By default, hablo will try to find the image to use for cards [automatically](https://git.marvid.fr/Tissevert/hablo/src/branch/master/src/Blog/Skin.hs#L36). It will look for a file with the [name](#name) of your blog and the extension `.ico`, `.gif`, `.jpeg`, `.jpg`, `.png` or `.svg` located at the root of the blog or in a directory called `image`, `images`, `pictures`, `skin` or `static`.
|
||
|
|
|
||
|
|
This option allows you to skip the auto-discover step or to use an image that wouldn't be found with the above method and directly tell hablo what file to use.
|
||
|
|
|
||
|
|
Note that not all cards generated for your blog will necessarily contain an image. If none of the expected path for card images exists and you don't provide one with this option, then pages won't embed an [open-graph](http://ogp.me/) picture in their card by default but articles with a [featured image](https://git.marvid.fr/Tissevert/hablo/wiki/Metadata#featured-image) will still do (and the image used for the card will be the featured image of the article).
|
||
|
|
|
||
|
|
Card images in themselves are only relevant once your blog is deployed and accessed by a browser or linked to. Hablo only includes a link to them or not, so of course the value of this option must be a relative path within your blog's structure. If you put a file outside, your web server will of course return 404 errors whenever something will read the corresponding header and attempt to access it.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
hablo --card-image skin/defaultCardImage.png
|
||
|
|
```
|
||
|
|
|
||
|
|
## Comments
|
||
|
|
|
||
|
|
`-C, --comments-at`
|
||
|
|
|
||
|
|
This option tells hablo on which [instance](https://git.marvid.fr/Tissevert/hablo/wiki/Architectural%20choices#fediverse) to look for the comments and expects a value containing a [link](https://en.wikipedia.org/wiki/URL#Syntax) to the instance itself as a scheme and an authority, no path.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
hablo --comments-at https://turtles.social
|
||
|
|
```
|
||
|
|
|
||
|
|
See the [metadata](https://git.marvid.fr/Tissevert/hablo/wiki/Metadata#comments) reference for a detailed explanation of how comments are activated for each articles.
|
||
|
|
|
||
|
|
## Favicon
|
||
|
|
|
||
|
|
`-f, --favicon`
|
||
|
|
|
||
|
|
Hablo looks for a favicon for your blog just like it does for [card images](#card-image) except it scans for a file called `favicon` and not the name of your blog.
|
||
|
|
|
||
|
|
Just like `--card-image`, this option can be used to skip looking for the favicon or to use a favicon with an arbitrary path. If you don't choose a favicon with this option and none is found automatically, your pages simply won't include one.
|
||
|
|
|
||
|
|
And, again, like for card images because they behave in very similar ways, the value expected is a relative path within your blog's structure.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
hablo --favicon skin/eyeOfTheTurtle.jpg
|
||
|
|
```
|
||
|
|
|
||
|
|
## Head file
|
||
|
|
|
||
|
|
`-H, --head`
|
||
|
|
|
||
|
|
The header section of the HTML pages includes several things such as the [open-graph](http://ogp.me/) metadata, the script inclusions for hablo's client code and for its [dependencies](https://git.marvid.fr/Tissevert/hablo/wiki/Deploying%20a%20hablo%20blog).
|
||
|
|
|
||
|
|
Use the `--head` option to add some arbitrary HTML elements to the header of your pages. This is the way to use a CSS theme for your blog, as is shown in the [customization](https://git.marvid.fr/Tissevert/hablo/wiki/Customizing%20your%20blog#how-do-i-use-a-custom-skin-) how-to.
|
||
|
|
|
||
|
|
## Name
|
||
|
|
|
||
|
|
`-n, --name`
|
||
|
|
|
||
|
|
Each blog has a name which is used in the default banner of your site and as the title of all pages (displayed in the tab's name and in the window name when your blog's tab is focused). Hablo infers it from the name of the directory containing it. It works on an absolute version the path it receives, so it won't suddenly think your blog is called `..` because you ran
|
||
|
|
|
||
|
|
```bash
|
||
|
|
hablo ..
|
||
|
|
```
|
||
|
|
|
||
|
|
from the path `turtles/articles`, it will still understand it's called «turtles».
|
||
|
|
|
||
|
|
You can use this option if you want to override this behaviour and provide a different name, for example because you simplified the name of your blog when you created a directory for it or because you want the name of your blog to contain characters prohibited in a directory name by your OS.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
hablo --name "Turtles/Paradize"
|
||
|
|
```
|
||
|
|
|
||
|
|
## Pages
|
||
|
|
|
||
|
|
`-p, --pages`
|
||
|
|
|
||
|
|
This option doesn't work yet but hablo will support static pages in addition to articles in a future release. Like [articles](#article-path), they will be expected to be located in a sub-directory called `pages/` but this option will allow you to use an arbitrary path within your blog's structure.
|
||
|
|
|
||
|
|
## Number of articles previewed
|
||
|
|
|
||
|
|
`-A, --preview-articles`
|
||
|
|
|
||
|
|
On the page that [lists](https://git.marvid.fr/Tissevert/hablo/wiki/Architectural%20choices#list-pages) only the most recent articles, only 3 articles are previewed by default. This option lets you change this number.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
hablo --preview-articles 5
|
||
|
|
```
|
||
|
|
|
||
|
|
will make all your short pages display 5 articles.
|
||
|
|
|
||
|
|
## Number of lines preview for articles
|
||
|
|
|
||
|
|
`-L, --preview-lines`
|
||
|
|
|
||
|
|
On each page that [lists](https://git.marvid.fr/Tissevert/hablo/wiki/Architectural%20choices#page-types) articles, only the first lines of each article are displayed. This option controls how many of them. By default, 10 lines will be displayed.
|
||
|
|
|
||
|
|
Note that this is a number of lines in the markdown files and has nothing to do with the amount of space used on the client screen once the blog gets rendered and viewed. Empty lines are included in the count, which starts right after the header of your markdown file (title and possible metadata). If you write articles with only a couple of very long one-line paragraphs, then all of them might get displayed.
|
||
|
|
|
||
|
|
## Remarkable config
|
||
|
|
|
||
|
|
`-r, --remarkable-config`
|
||
|
|
|
||
|
|
Hablo uses [remarkable](https://github.com/jonschlinkert/remarkable) to render your markdown articles to HTML. It calls it with very simple settings by default (`{html: true}`) but this option lets you set exactly what is passed to remarkable. This is useful to set a highlighter function for instance.
|
||
|
|
|
||
|
|
The file is read by hablo when the blog is generated and its content gets included into the client JS code so it can be located absolutely anywhere, even outside your blog's directory.
|
||
|
|
|
||
|
|
## Wording
|
||
|
|
|
||
|
|
`-w, --wording`
|
||
|
|
|
||
|
|
This option makes hablo look for the value of the texts used to [generate the pages](https://git.marvid.fr/Tissevert/hablo/wiki/Architectural choices#customization) in an [arbitrary file](https://git.marvid.fr/Tissevert/hablo/wiki/Template variables). It is useful to translate your blog (all texts are in english by default) or to give it a particular feel.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
hablo --wording /blogs/translations/fr-ca.conf /path/to/your/blog
|
||
|
|
```
|
||
|
|
|
||
|
|
The value of this option is used by hablo when your blog gets generated and is therefore completely independant from the path of your blog, the file it refers to can be located anywhere, including outside your blog structure.
|