Welcome to my notes
This is an example note. Every Markdown file in the notes/ folder shows up on the My Notes page, newest first.
Writing a note
Start the file with a title and a timestamp that includes a timezone:
---
title: My note
date: 2026-10-24T21:30:00+02:00
---
Then write anything Markdown supports:
- lists
- links
inline code
Quotes work too.
Adding images
Give the note its own folder, put the images next to its index.md and link them with a relative path. This note lives in notes/welcome/, next to city.png:


Adding maps
Put a <google-map /> tag on a line of its own to show a place. The map only loads from Google when the reader clicks it:
<google-map location="Hungarian Parliament Building, Budapest" zoom="16" caption="The Parliament on the bank of the Danube" />
Instead of location, you can give coordinates with lat and lng, and type="satellite" switches to satellite view.
Embedding code from GitHub
Put a <github-code /> tag on a line of its own with a link to a file on GitHub. Select lines on GitHub and use Copy permalink to get a link that is pinned to a commit and ends in the line range. The code is downloaded when the site is built and keeps the file’s own line numbers.
This is the function Astro uses to turn a note’s file path into its address, so welcome/index.md becomes /notes/welcome/:
<github-code url="https://github.com/withastro/astro/blob/e5a3a1bdec268933f01a0da3fbeb4e38bdf455c9/packages/astro/src/content/loaders/glob.ts#L59-L79" />
function generateIdDefault({ entry, base, data }: GenerateIdOptions, isLegacy?: boolean): string {
if (data.slug) {
return String(data.slug);
}
const entryURL = resolveEntryUrl(entry, base);
if (isLegacy) {
// Legacy behavior: use ID based on path, not slug
const { id } = getContentEntryIdAndSlug({
entry: entryURL,
contentDir: base,
collection: '',
});
return id;
}
const { slug } = getContentEntryIdAndSlug({
entry: entryURL,
contentDir: base,
collection: '',
});
return slug;
}
Embedding videos
Put a <youtube-video /> or <vimeo-video /> tag on a line of its own with the link to the video. The title and thumbnail are fetched when the site is built, and the player only loads from YouTube or Vimeo when the reader clicks play:
<youtube-video url="https://www.youtube.com/watch?v=dsTXcSeAZq8" />
start makes the video begin at a given time (a link with t=90 works too), and caption replaces the default caption, which is the video’s title and channel:
<vimeo-video url="https://vimeo.com/1084537" start="1m" caption="Big Buck Bunny, the open movie by Blender, from the one-minute mark" />
Embedding games and other WebGL
Put a game’s web build (from Unity, Godot or your own code) in a folder inside the note’s folder, and a <webgl-player /> tag on a line of its own pointing at it. The folder needs an index.html, or point src at the page that starts it. The game only loads when the reader clicks play:
<webgl-player src="./webgl-demo/" title="A spinning cube" caption="Drag or use the arrow keys to spin it" />
aspect sets the player’s shape ("16:9" unless you give one), and poster shows a picture from the note’s folder until it starts. Here’s a small game using both. Catch the stars, dodge the shards; your best score is kept in the browser:
<webgl-player src="./starfall/" title="Starfall" caption="Arrow keys or A and D, or drag, to steer" aspect="4:3" poster="./starfall/cover.png" />
Adding labels
List labels in the front matter and they appear as tags under the date, like the guide and example labels at the top of this note:
---
title: Welcome to my notes
date: 2026-10-24T21:30:00+02:00
labels: [guide, example]
---
Adding sources
List the sources of a note in the front matter and they appear after the article, numbered. Each one can be a bare link, a title with a link, or plain text such as a book. The sources below this note come from:
sources:
- https://docs.astro.build/en/guides/content-collections/
- title: Images in Astro
url: https://docs.astro.build/en/guides/images/
- The Markdown Guide, Matt Cone
Adding attachments
Put any files you want to share in an attachments/ folder inside the note’s folder. They are listed at the bottom of the note, and clicking one downloads it. This note’s folder looks like this:
notes/
welcome/
index.md
city.png
webgl-demo/
index.html
demo.js
starfall/
index.html
game.js
cover.png
attachments/
note-template.md
So note-template.md is listed below as a download. It is a starting point for your next note.
Sources
- docs.astro.build/en/guides/content-collections/
- Images in Astro
- The Markdown Guide, Matt Cone