9.9 KiB
Command line syntax
Hablo provides several arguments that can be used at runtime. You can view them by running
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.
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
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.
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. It will look for a file with the 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. It is of course only relevant if you have enabled Open Graph cards for your website by providing its deployment URL to hablo. Since it already knows the root URL of your website, this option expects only the local path to the image of course.
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 picture in their card by default but articles with a featured image will still do (and the image used for the card will be the featured image of the article).
hablo --card-image skin/defaultCardImage.png
Comments
-C, --comments-at
This option tells hablo on which instance to look for the comments and expects a value containing a link to the instance itself as a scheme and an authority, no path.
hablo --comments-at https://turtles.social
See the metadata 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 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.
hablo --favicon skin/eyeOfTheTurtle.jpg
Head file
-H, --head
The header section of the HTML pages includes several things such as the Open Graph metadata, the script inclusions for hablo's client code and for its dependencies.
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 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 of the path it receives, so it won't suddenly think your blog is called .. because you ran
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.
hablo --name "Turtles/Paradize"
Open Graph cards
-O, --open-graph-cards
Enables Open Graph cards in pages to display a pretty preview of them instead of the raw URL in links posted to social media. Note that this feature requires setting your site URL with --site-url.
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, 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 only the most recent articles, only 3 articles are previewed by default. This option lets you change this number.
hablo --preview-articles 5
will make all your short pages display 5 articles. This number of articles per short page is also used in the RSS feeds if you enable them with --rss.
Number of lines preview for articles
-L, --preview-lines
On each page that lists 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 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.
RSS
-R, --rss
Enables the generation of RSS feeds for each list of articles. The feed consists in an additional rss.xml file placed in the same directory as the index.html and all.html files generated for. The feeds only include the most recent articles exactly as the «short» versions of each list, which means that they are affected by the use of the --preview-articles option. When this option is enabled, hablo will also include links to the generated feeds in the list pages. Two template variables control respectively the content and the title of the link.
Note that this feature requires setting your site URL with --site-url.
Site URL
-u, --site-url
All the default content generated by hablo is independent from any host because it doesn't use any full URL with a host name. Enabling Open Graph cards or RSS feeds requires to know this information though, which is achieved by setting this option to the desired value.
Note that this is purely optional and you don't have to use this option if you don't care about Open Graph cards or RSS feeds. Setting it for no reason will trigger a warning.
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.
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.