196 lines
12 KiB
Markdown
196 lines
12 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`~~.
|
|
|
|
Also note that articles are partly optional : you can use hablo to generate a website with a fix content and no articles. In that case, just make sure no directory named `articles/` exists at the root of your website (see [pages](#pages-path)) and keep in mind that it should have static pages (hablo, just like other famous entities should not be invoked in vain and will exit in error suspecting something went wrong when invoked on an empty website with no articles and no pages, which to it means nothing to do).
|
|
|
|
## 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/banners/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/main/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. It is of course only relevant if you have [enabled](#site-url) 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](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).
|
|
|
|
```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 of 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"
|
|
```
|
|
|
|
## 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`](#site-url).
|
|
|
|
## Pages path
|
|
|
|
`-p, --pages`
|
|
|
|
In addition to «dynamic» lists of articles that grow over time, hablo supports «static» pages to allow you to publish relatively constant information related to your blog. Pages are 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.
|
|
|
|
So if for instance your blog is for a community of authors and a presentation of each of them is all you want to publish as «static» content, you could have this directory called «authors» and run `hablo` like this :
|
|
|
|
```bash
|
|
hablo --pages authors
|
|
```
|
|
|
|
This option is very similar to the one for [articles](#articles-path). Like the articles path, the pages path is of course relative to the blog's root. Pages are also partly optional : you don't have to have static pages in your blog in which case you should just make sure no directory named `pages/` exists at the root of your website and you have articles (because like we said above hablo is highly suspicious of being invoked to perform no work and will suspect this is a mistake and report it as an error).
|
|
|
|
Final tip : if you're using hablo to edit a static website with no articles, then you probably don't want to put your pages in a sub-directory but have them at the root of your website instead. This is possible, just remember that the current directory is called `.` in UNIX and run :
|
|
|
|
```bash
|
|
hablo -p .
|
|
```
|
|
|
|
## 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. This number of articles per short page is also used in the RSS feeds if you enable them with [`--rss`](#rss).
|
|
|
|
## 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.
|
|
|
|
## RSS
|
|
|
|
`-R, --rss`
|
|
|
|
Enables the generation of RSS feeds for each [list](https://git.marvid.fr/Tissevert/hablo/wiki/Architectural%20choices#page-types) 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 general lists. 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`](#number-of-articles-previewed) option. When this option is enabled, hablo will also include links to the generated feeds in the list pages. Two [template variables](https://git.marvid.fr/Tissevert/hablo/wiki/Template%20variables#rsslinks) control respectively the content and the title of the link.
|
|
|
|
Note that this feature requires setting your site URL with [`--site-url`](#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](#open-graph-cards) or [RSS feeds](#rss) 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%20choices#customization) in an [arbitrary file](https://git.marvid.fr/Tissevert/hablo/wiki/Template%20variables). 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.
|