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:
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:
- A title: displayed at the top of your post.
- A slug: a user-friendly unique identifier for your post, used in the URL. This one is optional and defaults to the timestamp the post was written on.
- The content: written in gemtext.
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.
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:
- Create an A record that points to 213.219.38.200
- Go to the Settings > Domain page of Smol Pub and add your domain
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:
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.
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:
- https://
.smol.pub
- gemini://
.smol.pub
- gopher://smol.pub/1/
Smol Pub allows you to use your own custom domain. Once set up, it will be available on both Web and Gemini:
- https://your-domain.com
- gemini://your-domain.com
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/
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.
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.
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
Guidelines
Smol Pub is a place where everyone should feel welcome and included.
Do
- Respect others
- Be friendly
- Have fun!
Don't
- Spam, malware, phishing
- Racism, bigotery, or hateful speech content
- Share anyone's private information
- Content which infringes any copyright or trademark
- Harmful and illegal activities
- Explicit Not Safe for Work (NSFW) content
Source