silicate-guide/content/tutorials/getting-started/new-comic-and-pages/index.md

+++
title = 'Adding a comic and comic pages'
show_toc = true
weight = 30
+++

{{< warning >}}
Page under redaction.
{{< /warning >}}

Ok! We have a blank site with Silicate installed!

Now, we can start the insteresting part: adding actual comic pages!

For this tutorial, we'll use [Pepper & Carrot](https://www.peppercarrot.com/) pages.

This guide has a premade archive with everything you'll need.
You can download it as a [tar.gz]() archive for Linux/Mac or a [zip]() for Windows.

{{< warning >}}
Archives will be created soon.
{{< /warning >}}

But if you have your own comic already, you can use your it too!


<!--more-->

## Setting up the comic

First off, let's create a `comic/` folder in `my_website/content/`.
It will be where all comic pages will go.

Now, we need to tell Silicate the title of the comic and give it a description.

It will be used in the archive.

Let's create an `_index.md` (notice the leading `_`) file inside `my_website/content/` with the following content:

```
+++
title = 'Pepper & Carrot'
+++

Comic [Pepper & Carrot webcomic](https://www.peppercarrot.com/en/) by David Revoy.

Licensed under Creative Commons Attribution 4.0 - www.peppercarrot.com.
```

This content uses the [Markdown](https://daringfireball.net/projects/markdown/) syntax,
so you can have some simple styling, like *\*italic text\**, **\*\*bold text\*\***, etc.

{{< warning >}}
Full description of Markdown possibilities will be added later.
{{< /warning >}}

This `_index.md` file tells Hugo that this folder is a *section*, that is, a group of pages.

Now, you should have this:

```
my_webcomic/
    hugo.toml
    content/
        comic/
            _index.md
```

> What is the weird text block with the "+++"?

This block is called a [*front matter*](https://gohugo.io/content-management/front-matter/#article),
it is used to add attributes to a page or a section, such as its title.

> The terminal just told me `ERROR Section '/comic' contains no pages!`!

That's normal: Silicate tries to check if there are problems when building your website
and refuses to do so when there is an obious problem.

To fix it, let's add the first page from Pepper & Carrot!

## Adding a new comic page

Create a `E01P01/` folder inside `comic/`. If you use your own webcomic,
you can use your own page title as a folder name (just avoid spaces and specials characters
because this folder name will be used as a URL for this page).

Then create a text file named `index.md`, without a leading `_` this time.

If you are on Windows, make sure the file created isn't
`index.md.txt`; Windows likes to hide file extensions from you, and you may need to force windows to display them.

This `index.md` file tells Hugo that the `E01P01` folder is a page -- not a section -- and that all other
files inside this folder belong to this page. This is what Hugo calls a "Page Bundle".

### Post content

Most webcomics will have a small "blog" post associated with a page -- a description,
some lore, etc.

You can do this by adding the post content to `index.md`.

Here, for example, we can add the credit of the first Pepper & Carrot page :

```
+++
title = 'Episode 1 - Page 1'
weight = 10
+++

Creative Commons Attribution 4.0 International license

------

Attribution to:

Art: David Revoy.

Scenario: David Revoy.

English (original version)

Proofreading: Amireeti, Alex Gryson.

------

Credit for the universe of Pepper&Carrot, Hereva:

Creation: David Revoy.

Lead Maintainer: Craig Maloney.

Writers: Craig Maloney, Nicolas Artance, Scribblemaniac, Valvin.

Correctors: Alex Gryson, CGand, Hali, Marno van der Maas, Moini, Willem Sonke.
```

This file also uses Markdown syntax and you can do the same formating as before!

> What is this "weight" in the front matter?

Don't worry about it yet, it's used for ordering.

And now, if we look at the website, we see this!:

![Page without picture](page_without_picture.jpg)

That's a start, but that's... not great, because there are no pictures yet.

The terminal also warned us about that:

`WARN  The comic page '/comic/e01p01' has no image matching the strips/**.{png,jpg,webp,PNG,JPG,WEBP} pattern!`

That warning is a bit of a mouthful, what it means is: "Silicate want pictures inside
a 'strips/' folder"

### Comic pictures

To fix this, all we need are pictures for the comic page.

So let's create a `strips/` folder inside `E01P01/`

Get the `pages/E01P01.jpg` file from the resources you downloaded -- or your
own comic page -- and add it inside the `strips/` folder.

You should now have this (and some other files and/or folders) :

```
my_webcomic/
    hugo.toml
    content/
        comic/
            _index.md
            E01P01/
                index.md
                strips/
                    E01P01.jpg
```

If your [website is running]({{% relref "tutorials/getting-started/site-creation" %}}#starting-your-site),
then the home page should display the page you just added like so!:

![Page with picture](page_with_picture.jpg)

Also, you can add multiple pictures inside `strips/`, Silicate will look for everything that is
a PNG, JPG or WEBP. On the website, they'll be ordered top to bottom by name, so you can make
a Webtoon-style long comic strip from many smaller strips.

Before we can add other pages, we need to take a look at some other topics first.

### Page ordering

Page ordering is important, and can get tricky.

Imagine you have a naming convention for your pages like so: `P1`, `P2`, ..., `P10`, `P11`, ...

If you order them by name, then you have a trouble, because they'll get ordered like so:

1. P1
2. P10
3. P11
3. P2
4. ...

It gets even worse if your pages have an actual name and no naming convention.

> Wait! Why not use a creation or publication date?

We could use a publication date, but imagine you want to add a new page between two others.
We now have *another* problem because you either can't or have to lie about the date to make it work.

That's why Silicate relies only on ...

#### Weight

The way Silicate handles ordering is by using the [*weight*](https://gohugo.io/methods/page/weight/#article) of the page.

You can see it like this: pages with a small weight floats up to the top and are first, pages with a big
weight sink to the bottom and are last.

![Weight schema](weight_schema.png)

You can set the weight with the line `weight = ...` in the front matter. It **has** to be a positive whole
number, things like `4.7` and `-1` won't work.

#### Best practice

What you should probably do is this:

- Page 1 gets a weight of 10
- Page 2 gets a weight of 20
- ...
- Page 50 gets a weight of 500

Why? Because starting at 10 then incrementing the weight by 10 each time lets you insert up to nine
pages before or after any page, should the need arise.


> Won't I run out of values? My webcomic is very long.

Even if you have a *lot* of pages -- say 4000 -- you would use
a weight of 40 000, which is _**way**_ below the maximum (which is at least *2 147 483 647*).


### Page creation date

If you want, you can set a [creation date](https://gohugo.io/content-management/front-matter/#date) for the page.
It will be displayed on the website under the page title.

You can add a `date='...'` field in the front matter.
The date format can be [multiple things](https://gohugo.io/content-management/front-matter/#dates).

Let's say the date of the page we just created was 9H35 the 2025 / May / 31, then the value to add is :

`date = '2025-05-31T09:35:00'`

(If we care only about the day, then we can add: `date = '2025-05-31'`)

Now, the page should be displayed with a creation date under its title!:

![Creation date](creation_date.jpg)

### Transcript

Some webcomics provides transcripts of their pages. Adding a transcript to a comic page
in Silicate is very simple: add a `transcript.md` text file next to your `index.md` and
Silicate will automatically add a "Transcript" button to display or
hide the content of `transcript.md` under your page.

Like for `index.md`, you can use any Markdown syntax to format your
transcript.

For the first page, let's write a small transcript:

```
Pepper the witch prepares a potion in a cauldron
while her cat Carrot lazily looks at her.

She sprinkles some powder in the cauldron.


**Pepper:**

> ...and the last touch.

> ...mmm probably not strong enough


She closes her eyes and dumps the whole powder box
into the mix while the cauldron bubbles with *Plop* sounds.
```

Now, you should have this file structure:

```
my_webcomic/
    hugo.toml
    content/
        comic/
            _index.md
            E01P01/
                index.md
                transcript.md
                strips/
                    E01P01.jpg
```

And the transcript should appear on the page!:

![Page with transcript](transcript.jpg)

## Automatic Archive page

The "Archive" page will automatically be kept up to date with the pages you add:

![Archive page](archive.jpg)

It will show the comic title and its description.

## Recap

Now you have most of what you need for a simple webcomic!

You can just keep adding new pages! The resource archive you downloaded
has what you need to add the first three pages of Pepper & Carrot.

Here's what to remember:

* Website configuraiton is in `hugo.toml`.
* Comic pages go inside `content/comic/`.
* Comic pages are folders with an `index.md` file.
* Comic page pictures go into a `strips/` sub-folder.
* Comic page transcripts go into a `transcript.md` file next to `index.md`.
* `index.md` has a *front matter* to set its title, ordering and creation date.
* Ordering is done through weights. Light/Small = first, heavy/big = last.