Smol Pub Manual

"So what's a Smol Pub anyway?" says you, as you pick-up the notebook from the counter. The cover reads "Your journal on the small internet". Curious, you go on.

Anything you write in this notebook will be available on the Web, Gemini and Gopher. Instead of a pen, you'll use the web interface or CLI to write.

Your journal on the small internet

Gemini? Gopher? What are these words?! If you already know, feel free to skip this section. Otherwise, read on...

The Web isn't the only Internet protocol, in fact it wasn't even the first one. Gopher predates the Web and is still in use today. It's actually gaining in popularity. Gemini, a recent Internet protocol that explores the space between the Web and Gopher brings back the late 90's excitement over what Internet can be: a place where people connect. Both Gemini and Gopher share simplicity. There's no ads, JavaScript code and cookie-tracking technology. Just plain text. There's no notification, no point system, just real people. The small net is also slow. It's a place for longer-form content. It's bare: there's no bell and whistle. Only text. It's a place of substance.

Here's a definition I really like:

The Small Internet happens
when a few people
use simple protocols
to talk with each other
and nobody else.

The small net is about connecting using simple technologies.

As spring puts it on his phlog:

On the Large Internet, communication is ubiquitous, but conversation is a radical act.

He then goes on and says:

There aren't any spectators
on the Small Internet,
only participants.

When you write on Smol Pub, your content will be available on the Web, but also on Gemini and Gopher which constitute parts of the small internet. You can't connect there with your web browser. Both protocols don't use the https scheme we're so used to. Without setting any domain names, here is where your journal is hosted with Smol Pub:

https://<username>.smol.pub
gemini://<username>.smol.pub
gopher://smol.pub/1/<username>

When (if) you do set a domain, the Web and Gemini address becomes:

https://your-domain.com
gemini://your-domain.com

Notice the gemini:// and gopher://?

It begs the question: how can I browse the small net? Well, luckily enough, there are many browsers to do so. The two I'd recommend using are:

Lagrange
Amfora

However, note that you don't need such a browser to use Smol Pub. After all, everything you write is fully available on the web. Speaking of which, let's see how we write with Smol Pub.

Writing with Gemtext

Gemtext is the text format used by Smol Pub to let you write anything: a new post, a page, or even update the header / footer section of your journal. Smol Pub will take care of converting the Gemtext to HTML when viewing form the web, and to Gophermap when exploring from Gopher. Gemtext is a radically simple text format that's part of the Gemini project. It looks like a simplified version of markdown. You probably already know Gemtext, look:

# Top level title
## Second level title
### Third level title

Straightforward, right? Note that Gemtext (and Gemini's) philosophy is simplicity, so it doesn't support more than 3 level of heading. Let's look at lists now:

* List item
* List item

Want to add some ascii art? Or maybe some code? Use the raw text construct:

​```
Raw text
​```

How about quoting?

> Quoted text

Finally, links. In Gemtext, there can only be a single link per line. Here is how it's formatted:

=> https://example.com This is a link
=> gemini://example.com This is a link to a gemini page
=> //example.com This is a schemaless link

Now that you learned how to use Gemtext, let's write our first post.

New post

Smol Pub lets you write posts. What are they? They are like pages in your journal. Each post gets added to your homepage, and is preceded by the date at which it's been created. To write a post, need three things:

Select "New post". Time to write your Hello World post!

Tell the world about you with an about page

While posts are automatically added to your journal and to your feeds, a page isn't. A page is just gemtext document. You can write anything you want on it: a home for a project you are working on, a list of your favorite links on the small net, or even an about page tell people a little more about you. So how about we go ahead and do that? Just head over the "Pages" and select "New Page". Simply add a slug (how about "about"?) and some text about yourself. The page won't be listed on your journal, only posts are. To list it, add a gemtext link:

=> /about About me

A good place to add links to pages is your header or footer, let's learn about them.

Let's add a header and footer to your journal

Your journal should reflect who you are. And while your posts are the substance, sprinkling a little bit of fun on your homepage can go a long way. If you go to the Settings section, you will see that you can customize the header and footer section of your journal. The header is the part above all your posts, and the footer is what's beneath. You can use Gemtext to edit these sections.

Add your email address!

The best way to interact on the small web isn't with DMs or comments, but with good old out-of-band technologies that have been there for a long time like emails. It's very common for authors to leave their email address. That way people can let you know if they wrote something that quotes something in your post, or simply to engage in a discussion with you.

Plain text doesn't mean boring

As you will see when you explore the small net, people can get very creative with ascii art on their homepage!

Use pages to write drafts

Since pages aren't published on your journal, you can use them to start drafting posts. To organize yourself, you can give their slug a "draft-" prefix. Once you are happy with your draft and want to publish it, copy and paste it as a post, and delete the draft.

Add CSS

Smol Pub comes with a dark and light css theme, however if you'd like to personalize further how your journal looks like on the web, it's possible to add a CSS stylesheet by visiting Customize > Theme.

Looking for inspiration?

Keep in mind that simple colors, good contrast and readable typography goes a long way. After all, you're not on the small web to design the next parallax-animated blog, aren't you? Let the rest of the web worry about their CSS.

Add an external stylesheet

When you get to Settings > Theme, you will see that you can add an external stylesheet. A good place to pick one from is cssbed. They list simple class-less CSS theme that you can link up directly.

cssbed

Let's add the "water.css" theme. To do that, copy and paste "https://cdn.jsdelivr.net/gh/kognise/water.css@latest/dist/dark.css" to the External stylesheet input of the Settings > Theme page. And that's it!

Feeds for syndication

All your posts are automatically syndicated in your atom feeds. This makes it straightforward for anyone to follow your journal with their favorite feed readers. Smol Pub maintains three feeds for you, one for each supported protocol:

https://<username>.smol.pub/atom.xml
gemini://<username>.smol.pub/atom.xml
gopher://smol.pub/<username>/0/atom.xml

Each feed links to their respective protocol's mirror of your posts.

Add this link to your footer?

It's a good practice to show a link to your feed from your footer. That way, users visiting from all places can add your journal to their good old RSS software.

Attach your custom domain

If you don't have a domain yet, I'd strongly suggest to go ahead and get one! Your domain represents yourself online. You can use it for your journal, but also for your emails. You can use different subdomains for different purpose. And the best thing is that you can always have your domain point to any where you'd like. You are never locked anywhere.

To attach your domain to your Smol Pub journal, go to your domain's DNS settings page an:

That's it. Give it a few hours to propagate and you are all set. Smol Pub will automatically generate an SSL certificate with Let's Encrypt to make your journal available over https.

Upload files

You can upload up to 100 MB of files. You can link to those files directly from your posts using gemtext's link syntax. If you need more storage, feel free to contact me directly.

Images

To upload an image, head over to Files and select it. Once it's uploaded, you can find its URL by clicking on it in the list. To insert it in your posts, use a gemtext link:

=> link-to-my-image.png

On the web, Smol Pub will recognize that it's an image thanks to the extension and will automatically add an image tag.

Export your posts

Head over to Settings > Export to download a tar.gz containing all your posts.

Delete your account

You can completely delete your account by going to Settings > Delete account.

Discover your neighbors!

The small net is all about reading and interacting with others. And the best way to discover others is through the Smol Pub feed:

Feed

Go ahead and read what others have to say! Feel free to quote them on your own posts. There's no notification system of any sort, just people reading and writing. You can also notify someone when you wrote something quoting them, if they left their email on their page. The small net is all about limited but meaningful exchanges, so take it slow and enjoy the process of having your own, dedicated thought space!

Manage your journal with the CLI

If you'd rather not use the web at all, Smol Pub has you covered. It comes with a companion bash script to publish and edit your posts from the comfort of the command line.

Download smolpub.sh

Installation

After you've downloaded the script, make it executable:

chmod +x smolpub.sh

Now, I suggest adding it to your path so you can invoke it from anywhere. To do that, let's move it to:

mv smolpub.sh /usr/local/bin

Alright, the last part is to save your token. Head over to the Settings page, and copy your token to `~/.config/smolpub`. Now we are ready to use it!

How to use

smolpub.sh takes a single argument: the name of a file to publish or edit.

Let's create a file:

touch hello-world

Now, let's edit it with our favorite editor:

# Hello, from the CLI

He always wore his sunglasses at night.

Notice that there's a blank line between the title and the content. That's required for the script to function.

Let's publish the post:

smolpub.sh hello-world

That's it! Let's edit it now:

# Hello, from the CLI

He always wore his sunglasses during the day.

To update, just run the same command as above:

smolpub.sh hello-world

It's now edited. The name of the file is used as the slug for your post. That's why you need to make sure to remove any extension (e.g. .txt) before you publish your post.

Frequently Asked Questions

What is the URL of my journal?

As your journal is available on the Web, Gemini and Gopher, it has three URLs:

Smol Pub allows you to use your own custom domain. Once set up, it will be available on both Web and Gemini:

My domain name doesn't point to my Gopher journal

Due to the way Gopher requests work, it's unfortunately impossible to virtually point to your journal (virtual hosting). The only way to access your journal from Gopher is gopher://smol.pub/1/<username>.

What's Gemini? What's Gopher?

Both are Internet protocols. While the Web typically displays pages using HTML, Gemini and Gopher focus on plain text. This makes them a great medium for long-form, distraction-less writing.

Gemini Quickstart

What's a slug?

Slugs are the part of the URL that refers to your post. On m15o.smol.pub/hello-world, hello-world is the slug. It needs to be unique for your blog. Think of it as an user-friendly ID.

Which format can I use to write my posts?

Smol Pub uses the Gemtext (Gemini Text) format. Gemtext is a markdown-inspired text format with a limited set of features. Smol Pub automatically converts Gemtext to HTML or Gophermap to ensure your content is available on the Web, Gemini and Gopher.

Is it possible to use Gemini or Gopher directly to write posts?

No. In order to write posts on Smol Pub, the preferred way is through the web interface. However, if you'd rather not use the web, you can use the simple CLI tool.

What are the supported platforms for the CLI?

The CLI is a bash script, so any platform that can run bash can use the CLI. That includes Mac, Linux, and Windows as long as it's using a terminal that can run bash.

Download the CLI

How can I add an image?

Smol Pub allows you to upload files, including images. You can do so from the Files section. Once uploaded, you can click on the file to get its URL and link it within your post using a Gemtext link.

Password lost? Want to change username? Any other question?

You can write me directly at m15o@smol.pub