Publish markdown files easily
howtopages.casa includes a smolmd module permitting to render markdown files in a smolweb site format.
On your server space (via FTP/SFTP), you have access to a markdown folder containing a sample of smolweb site writen in markdown files. You can modify them.
Files in the markdown folder are accessible through the md subfolder of the main URL of your site : https://your-pseudo.pages.casa/md/
Detail of markdown folder
markdown
├── _footer.md
├── _header.md
├── blog
│ └── first-post.md
├── contact.md
├── index.md
├── prefs.ini
└── style.css
prefs.ini
This file contains some information useful to generate metadata of the pages and the RSS feed.
# The author name of the site
site_author = "Adële"
# The title of the site
site_title = "Adele's smolweb site"
# The main language of the content
site_language = "en"
# The options of the directory containing posts (in a blog way)
site_autoindex_subfolder = "blog/"
site_autoindex_last_first = true
site_autoindex_date_format = "Y-m-d H:i"
site_autoindex_posts_per_page = 5
site_autoindex_include_first_paragraph = true
_header.md
This file, in markdown, is included at the begining of all HTML pages. Useful to put a site title and a menu. Do not use # Title (for H1), H1 is reserved for the titles of the posts and pages. Prefer **Title** format.
An unordered list (line starting with - or * and a space) is used to build the header menu.
**My smolweb site**
- [About](/md/)
- [Blog](/md/blog/)
- [Contact](/md/contact.md)
- [RSS](/md/blog/rss.xml)
_footer.md
This one is for the foot of all HTML pages.
An unordered list (line starting with - or * and a space) is used to build a menu. In the footer menu, links get a rel="me" attribute which is clever to validate account links in social networks of the Fediverse.
* [Mastodon](https://mastodon.social/@my_mastodon_account)
* Hosted on [pages.casa](https://pages.casa/)
* Content under [CC-BY-NC](https://creativecommons.org/licenses/by-nc/4.0/deed.en) Me
index.md
This is the home page of the smolweb site. Put a description of you or/and your site.
# Welcome on my smolweb site
I'm me and I like to post article in [markdown format](https://commonmark.org/help/)
blog/*.md
markdown files in the blog directory (in fact, the folder defined by site_autoindex_subfolder in prefs.ini), is used to build the blog system. Each .md file is an article. It should include a line starting by # to define the title of the article, and a line with a date in a clear format such as 2024-03-30 20:50 to determine the date of publication and then order articles correctly.
Get more info about markdown syntax.
# This is my first post
2024-02-24 20:00
It seems to work!
style.css
You can customize your smolweb site with this stylesheet. Here is the default one if you break the whole presentation ;-)
html {
font-size: 100%;
}
body {
margin: 0 auto;
padding: 0;
max-width: 1024px;
font-family: system-ui, sans-serif;
font-weight: normal;
}
main {
margin: 0 1rem;
}
header {
padding: 0.2rem;
}
header p strong {
font-size: 2.2rem;
margin: 2rem 1rem;
font-weight: bold;
}
header p small {
font-size: 0.8rem;
}
nav ul {
list-style-type: none;
border-left: 1px solid #ccc;
margin: 0;
padding: 0;
}
nav ul li {
display: inline-block;
border-right: 1px solid #ccc;
border-bottom: 1px solid #ccc;
padding: 2px 10px;
margin: 0;
}
nav ul li a.active {
font-weight: bold;
}
h1
{
font-size: 1.8rem;
}
h2
{
font-size: 1.5rem;
}
h3
{
font-size: 1.2rem;
}
pre, code {
font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, 'DejaVu Sans Mono', monospace;
tab-size: 1em;
}
code {
background-color: #eee;
color: #060;
}
pre {
padding: 1rem;
margin: 1rem 0;
overflow-x: auto;
background-color: #111;
color: #6f6;
border-radius: 0.5rem;
}
pre code {
background-color: #111;
color: #6f6;
}
li {
margin-left: 1rem;
}
p {
margin: 1rem 0;
}
a {
color: #009;
text-decoration: none;
}
blockquote {
background-color: #eee;
padding: 0.5rem 1rem;
margin: 0 0 0 0.5rem;
border-radius: 0.5rem;
}
img {
max-width: 100%;
}
footer {
margin-top: 20px;
}
@media (prefers-color-scheme: dark) {
body {
color: #eee;
background-color: #444;
}
a {
color: #99f;
}
blockquote {
color: #fff;
background-color: #333;
}
code {
background-color: #111;
color: #6f6;
}
}
RSS Feed
An rss feed is automatically generated for the posts of a folder. Just use the url of the folder and apend /rss.xml.
The rss feed of the folder defined by site_autoindex_subfolder in prefs.ini is automatically proposed to your visitors in the metadata of your site. For the blog folder it is https://your-pseudo.pages.casa/md/blog/rss.xml
It contains last articles with full content.
Other files
You can include image files and link them in markdown content with the syntax:
 for a relative link from the .md file if image and markdown file are in the same folder.
 for a relative link from the root of your site.
.png .gif .jpg .jpeg .ico and .webm are supported.
Tips and tricks
Create a post easily with vim
Vim manages sftp url and it is very easy to create a new post with it.
Example:
vim sftp://your-pseudo@mimosa.pages.casa/markdown/blog/my-new-post.md`
Add your title, the date, the content and [Esc] :wq [Enter] (type an additional :q [Enter] if vim does not close)
Edit your site directly in your file explorer on GNU/Linux
Almost file explorers, such as thunar or nautilus, manage remote server with sftp protocol.
With Debian/Ubuntu, your need packages gvfs-fuse, gvfs-backends and sshfs.
sudo apt install gvfs-fuse gvfs-backends sshfs
With Archlinux, gvfs and sshfs are needed.
sudo pacman -S gvfs sshfs
Then, your can access your file on pages.casa server in your file explorer.
Hit [Ctrl]+L to open location entry and paste the url sftp://your-pseudo@mimosa.pages.casa/markdown/ and [Enter]
If it doesn’t work, check that your user is in fuse group. Or add it:
adduser $USER fuse
(you may have to restart your session)