customization

customize your site's appearance with colors and menus. use the dashboard UI or set values directly in your index.md frontmatter.

settings.json#

how your site behaves lives in one file, settings.json, in the site folder. the dashboard and the app write it for you when you change a setting; you can also edit it by hand. every key is optional and a missing file means the defaults.

{
  "version": 1,
  "title": "my site",
  "language": "en",
  "menu": { "header": [{ "label": "home", "url": "/" }], "footer": [{ "label": "rss", "url": "/rss.xml" }] },
  "logo": { "text": "my site", "font": "Georgia", "size": "18px", "color": "#333" },
  "list": { "view": "list", "visible": true, "dates": "created", "sizes": true, "icons": true, "sort": "date", "order": "desc" },
  "page": { "metadata": true, "export": false, "anchors": true, "highlighting": true },
  "header": { "sticky": false }
}

• list.view: list, cards or grid
• list.dates: created, modified or none to hide the date column
• list.sort and list.order: name, date or size; asc or desc
• page.metadata: the created and updated dates under a page
• page.export: copy, ChatGPT and Claude links under a page
• a settings.json inside any subfolder overrides these for that folder and everything under it. logo and header only work in the site root
• the older frontmatter keys below (header_menu, logo_text, show_file_list, default_view) still work; settings.json wins where both are set, and the first save from the dashboard moves them out of index.md for you

style.css#

drop a style.css in the site folder and it is added after the theme on every markdown page. use it for anything the settings cannot express. (html pages are served as-is and load their own stylesheets, see publish a hand-written html site.)

two ways to customize#

1. dashboard UI#

1. go to your site on tinydot.com
2. click settings (gear icon)
3. click "customize"
4. use color pickers and menu editors
5. save changes

2. frontmatter in index.md#

add customization directly in your site's index.md file:

---
color:
  background: "#ffffff"
  text: "#1a1a1a"
  border: "#e5e5e5"
  muted: "#666666"

header_menu:
  - title: home
    url: /
  - title: about
    url: /about

footer_menu:
  - title: rss
    url: /rss.xml
---

frontmatter customization is useful when you edit files locally or want version-controlled settings.

colors#

available color properties:

color examples#

minimal light theme:

color:
  background: "#ffffff"
  text: "#000000"
  border: "#eeeeee"
  muted: "#888888"

dark theme:

color:
  background: "#1a1a1a"
  text: "#ffffff"
  border: "#333333"
  muted: "#888888"

menus#

three menu areas available:

• header_menu - top navigation
• footer_menu - bottom links
• sidebar_menu - sidebar navigation (template-dependent)

menu example#

header_menu:
  - title: home
    url: /
  - title: blog
    url: /blog
  - title: about
    url: /about

footer_menu:
  - title: rss
    url: /rss.xml
  - title: contact
    url: mailto:hi@example.com

sidebar_menu:
  - title: projects
    url: /projects
  - title: notes
    url: /notes

each menu item needs:

• title - display text
• url - link destination (relative or absolute)

logo#

tinydot automatically detects a logo file in your site root and uses it as the site logo in the header. supported names: logo.png, logo.jpg, logo.jpeg, logo.svg, logo.webp, logo.avif.

favicons work the same way: favicon.png, favicon.ico, favicon.jpg, favicon.jpeg, favicon.svg, favicon.webp. if you don't add one, your logo is used.

logo sizing#

control the logo dimensions with frontmatter in your root index.md:

---
logo_height: 20px
logo_width: 120px
---

set one or both. aspect ratio is preserved if you only set one dimension.

the logo file is hidden from your site's file listing automatically — you don't need to do anything to keep it out of the way. it stays reachable at its own url.

hiding any other file#

name a file so it starts with a dot and it disappears from your file listing, rss feed and archive, while still being served at its own url. useful for images and assets you link to from your pages but don't want listed:

.hero-background.jpg   → hidden from listings, still at /.hero-background.jpg

folders work the same way, which is why tool folders like .obsidian and .git never show up on your site.

to hide a page and make its url stop working too, use a draft instead — see drafts.

logo text#

if you don't have a logo image, you can set text-based logo:

---
logo_text: my site
logo_text_font: Georgia, serif
logo_text_font_size: 18px
logo_text_color: "#333"
---

images#

customize how images in content blocks are displayed:

image:
  shadow: "0 4px 12px rgba(0,0,0,0.15)"
  radius: "8px"
  border: "1px solid #eee"

image examples#

no styling (flat images):

image:
  shadow: "none"
  radius: "0"
  border: "none"

polaroid style:

image:
  shadow: "0 4px 16px rgba(0,0,0,0.2)"
  radius: "2px"
  border: "8px solid white"

color derivation#

when you set both background and text colors, tinydot automatically derives intermediate colors you don't explicitly set:

• --color-bg-muted (11% towards text)
• --color-bg-subtle (7% towards text)
• --color-bg-light (4% towards text)
• --color-border (18% towards text)
• --color-border-light (12% towards text)
• --color-text-muted (40% towards background)
• --color-text-secondary (20% towards background)
• --color-text-light (60% towards background)

this means setting just background and text is enough for a complete dark or light theme. explicitly set colors always take priority over derived ones.

theme settings#

control dark/light mode behavior:

theme:
  default: dark
  toggle: false

set theme.default: dark to load your site in dark mode on first visit. if the toggle is visible, visitors can switch and their preference is saved in localStorage.

set theme.toggle: false to hide the theme switcher, locking your site to the default theme.

behavior settings#

toggle options that change site behavior:

frontmatter example#

header:
  sticky: true

content:
  heading_anchors: true
  syntax_highlighting: false

show_file_list: false

set show_file_list: false to hide file listing on folder pages, showing only the index.md content.

when content.heading_anchors is enabled, each heading gets an anchor link that appears on hover. readers can click or copy the link to share a direct URL to that section.

templates (COMING SOON!)#

each template has its own style:

• finder - file browser aesthetic, supports hover and list colors
• future - retro web style, supports link colors
• romi - minimal design, supports link colors
• human - readable

full example#

complete index.md with all customization:

---
title: my site
date: 2026-01-01

color:
  background: "#fafafa"
  text: "#1a1a1a"
  border: "#e0e0e0"
  muted: "#666666"
  link: "#0066cc"

theme:
  default: light
  toggle: true

image:
  shadow: "0 4px 12px rgba(0,0,0,0.1)"
  radius: "8px"
  border: "none"

header_menu:
  - title: home
    url: /
  - title: blog
    url: /blog
  - title: about
    url: /about

footer_menu:
  - title: rss
    url: /rss.xml
  - title: source
    url: https://github.com/username/site
---

# welcome

this is my site.

when settings are not enough: write html#

every setting on this page shapes the template tinydot puts around your markdown. if you want a page the template cannot express, write it as html. an .html file is served exactly as written, with your own css, javascript, fonts and layout, and nothing of ours around it. a stylesheet next to it loads with a plain relative link. markdown and html pages can live in the same folder, so one custom page does not mean giving up the rest.

see publish a hand-written html site.

related#

• metadata - frontmatter basics
• sites - site settings