Documentation

Getting Started

st.ht is a simple markdown hosting service. Upload a zip file containing markdown files, and we'll create a website at username.st.ht.

Basic Usage

Create an account and login
Create a zip file with your markdown content
Upload the zip file through the admin panel
Your site will be available at username.st.ht

Markdown Files

All .md files in your zip will become pages on your site. The filename becomes the URL:

about.md → username.st.ht/about
projects.md → username.st.ht/projects
index.md → username.st.ht/ (home page)

Special Files

index.md - If present, becomes your site's home page instead of the default page listing
Files starting with ._ are ignored (Mac metadata files)

Front Matter

Add YAML front matter to the top of your markdown files to control page properties:

---
title: My Page Title
template: custom
---

# My Page Content

This is the content of my page.

Available Front Matter Properties

title - Sets the page title (overrides title extracted from first heading)
template - Specifies which template to use for rendering this page

Example

---
title: About Me
template: profile
---

# About Me

I'm a developer who loves building simple, useful tools.

Custom Templates

Customize how your pages look by including HTML templates in your zip file.

Template Structure

Create a _templates/ directory in your zip file and add .html files:

my-site.zip
├── index.md
├── about.md
└── _templates/
    ├── default.html
    └── profile.html

Template Variables

Your templates have access to these variables:

{{.Page.Title}} - The page title
{{.Page.Slug}} - The page URL slug
{{.Page.Template}} - The template name
{{.Page.CreatedAt}} - When the page was created
{{.HTMLContent}} - The rendered HTML content from markdown

Example Custom Template

Create _templates/profile.html:

<!DOCTYPE html>
<html>
<head>
    <title>{{.Page.Title}}</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 40px; }
        .profile { border: 2px solid #333; padding: 20px; }
    </style>
</head>
<body>
    <div class="profile">
        <h1>{{.Page.Title}}</h1>
        {{.HTMLContent}}
    </div>
</body>
</html>

Using Custom Templates

Reference your template in the front matter of your markdown files:

---
title: About Me
template: profile
---

# About Me

Content here will be rendered with the profile template.

Default Template

If you create _templates/default.html, it will be used for all pages that don't specify a template or specify template: default in their front matter.

Features

Syntax Highlighting

Code blocks are automatically highlighted:

```go
func main() {
    fmt.Println("Hello, world!")
}
```

Wikilinks

Link between pages using double brackets:

Check out my [[about]] page or my [[projects]].

Search

Your site automatically includes search functionality accessible via API at /api/search?q=query

Tips & Best Practices

Start with an index.md file for your home page
Use descriptive filenames - they become your URLs
Test your templates locally before uploading
Keep templates simple and lightweight
Use front matter consistently across your pages
Remember that re-uploading replaces all content

Example Site Structure

my-blog.zip
├── index.md              # Home page
├── about.md              # About page  
├── blog/
│   ├── first-post.md     # Blog post
│   └── second-post.md    # Another post
└── _templates/
    ├── default.html      # Default template
    └── blog-post.html    # Blog post template

This creates:

username.st.ht/ (home page)
username.st.ht/about
username.st.ht/first-post
username.st.ht/second-post