💾 Archived View for smol.pub › manual captured on 2024-07-08 at 23:53:34. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-11-30)
-=-=-=-=-=-=-
"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.
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:
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.
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:
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.
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!
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.
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.
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.
As you will see when you explore the small net, people can get very creative with ascii art on their homepage!
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.
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.
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.
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.
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!
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.
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.
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.
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.
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.
Head over to Settings > Export to download a tar.gz containing all your posts.
You can completely delete your account by going to Settings > Delete account.
The small net is all about reading and interacting with others. And the best way to discover others is through the Smol Pub 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!
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.
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!
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.
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:
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>.
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.
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.
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.
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.
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.
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.
You can write me directly at m15o@smol.pub
Smol Pub is a place where everyone should feel welcome and included.