vowel 0.1.46 → 0.2.2

package/docs-source/docs/deploy.md

@@ -0,0 +1,67 @@
+---
+title: Deploy
+description: Get going.
+---
+
+See the [quickstart](/docs/quickstart) for instructions on how to use npm.
+
+**Note on URLs:** This guide includes instructions for Vercel, which specify a deploy option called `cleanUrls`. This will trim the `.html` extension from your deployment URLs. If you configure your own deploy, ensure you use clean URLs or your links will not work.
+
+# GitHub
+
+If you have a GitHub repository of Markdown files, you can deploy them on Vercel automatically on changes.
+
+Add a `vercel.json` file to the root of your project with the following contents:
+
+```js
+{
+  "cleanUrls": true,
+  "outputDirectory": ".output",
+  "buildCommand": "npx -p svelte@next -p vowel@latest npx vowel build"
+}
+```
+
+Then create a new Vercel project and connect your GitHub repository.
+
+When you push changes to your repository, your Vercel project will automatically rebuild.
+
+# npx
+
+You can manually build your project with `npx`. Run this command:
+
+```
+npx -y -p svelte@next -p vowel@latest npx vowel build
+```
+
+The build command will create a `vercel.json` file at the root of your project with the necessary configuration for a Vercel deploy. Now deploy to Vercel:
+
+```
+npx vercel --prod
+```
+
+(The `--prod` flag will deploy to production.)
+
+If you don't want to use the Vercel CLI, you can deploy the `.output` directory to any server that supports static HTML.
+
+# npm
+
+If you set up your project with npm, you can include a `build` command in your `package.json`:
+
+```diff
+    "scripts": {
+      "dev": "vowel",
++     "build": "vowel build"
+    },
+```
+
+Run `npm run build` (`vowel build`) to build your website.
+
+Now you can deploy to Vercel:
+
+```
+npx vercel --prod
+```
+
+(The `--prod` flag will deploy to production.)
+
+If you don't want to use the Vercel CLI, you can deploy the `.output` directory to any server that supports static HTML.

package/docs-source/docs/file-structure.md

@@ -0,0 +1,31 @@
+---
+title: File structure
+breadcrumb: Files
+description: Organize your files.
+---
+
+Your website is made of folders and markdown files. Every folder should have a `home.md` file. Every folder can also have a `settings.md` file to apply folder-level settings, such as the `breadcrumb`.
+
+Almost every file and folder represents a page on your website:
+
+- `home.md` is your homepage, `/`
+- `about.md` would be your about page, `/about`
+- `blog/home.md` would be your blog homepage, `/blog`
+- `blog/hello-world.md` would be a blog post, `/blog/hello-world`
+
+(File names like `Hello World.md` also seem to work fine so far.))
+
+Even if a folder doesn't have a `home.md` file, it will still generate a page, so long as it contains any markdown files. So, if you have a `blog` folder with posts inside it, Vowel will generate a `/blog` homepage even if you don't have a `/blog/home.md` file.
+
+There are a few special files and folders:
+
+- `assets/` contains some static files
+  - `assets/styles.css` contains your stylesheet, which will be automatically applied if present
+  - `assets/favicon.png` is your favicon
+- `templates/` is a commonly-used directory in Obsidian projects, so it will be ignored
+- A `settings.md` file will not generate a page. If you want a page called `settings`, you can create a `/settings/home.md` file.
+- `.cache.json`
+- `.output/`
+- `vercel.json`
+
+Any files prefixed with a period will be ignored, as will any files that are not markdown.

package/docs-source/docs/folder-settings.md

@@ -0,0 +1,23 @@
+---
+title: Folder settings
+breadcrumb: Folders
+description: Configure your project.
+---
+
+Every folder should have a `settings.md` file with one property:
+
+- `breadcrumb`: A navigation label
+
+At the root of the project, there should be a global settings file with the `breadcrumb` property and any of the following properties:
+
+- All folder settings, plus
+- `title`: Website title
+- `robots`
+  - `google`: Allow Google Search indexing (`true`/`false`)
+  - `google_images`: Allow Google Image indexing (`true`/`false`)
+  - `ai`: Allow AI training (`true`/`false`)
+- `domain`: Full root URL for the website domain (e.g. `https://example.com`)
+- `author`: Website author credit for RSS and copyright
+- `icon`: An emoji to use as the site favicon
+- `slogan`: The website slogan
+- `logo`: The website logo

package/docs-source/docs/home.md

@@ -0,0 +1,55 @@
+---
+title: Documentation
+description: Learn how to use Vowel.
+---
+
+Let's get started.
+
+
+## npx
+
+npx is the easiest way to use vowel:
+
+```
+npx -y -p svelte@next -p vowel@latest npx vowel
+```
+
+Vowel will attempt to generate a website based on the contents of your file.
+
+## npm
+
+Create a directory. Then, open that directory and run these commands in your terminal:
+
+```bash
+npm init --y && npm i vowel svelte@next
+```
+
+Edit your `package.json` to add these `scripts`:
+
+```json
+{
+	"dev": "vowel",
+	"build": "vowel build"
+}
+```
+
+Now run `npm run dev`.
+
+## Starter files
+
+Create `home.md` and enter some basic information
+
+```md
+# Your website
+
+Lorem ipsum...
+```
+
+Create `settings.md` and enter some basic information in the frontmatter:
+
+```
+---
+breadcrumb: Home
+domain: https://example.com
+---
+```

package/docs-source/docs/images.md

@@ -0,0 +1,10 @@
+---
+title: Images
+description: How to host images.
+---
+
+You can put images in the `assets` folder, but this is discouraged, as it could result in a large bandwidth bill from your hosting provider.
+
+We recommend hosting images elsewhere.
+
+Images hosted on imgix will automatically be optimized, compressed, and formatted.

package/docs-source/docs/items.md

@@ -0,0 +1,13 @@
+# Items
+
+With Vowel, you can create reusable pieces of content and embed them throughout your website.
+
+To create one, prefix a file or folder with a `$`, such as `$faqs`. The file or folder will not produce a page, but the content can be displayed on other pages, like so:
+
+```md
+Here are answers to common questions:
+
+/$faqs?count=10
+```
+
+This also allows richer content, as the item will be displayed with frontmatter.

package/docs-source/docs/pages.md

@@ -0,0 +1,141 @@
+---
+title: Pages
+description: Create content.
+---
+
+The `body` element on each page has a class representing the current page. The homepage has classes `"page home"`, while a blog post might have `"page blog-hello-world"`.
+
+Vowel attempts to construct a logical semantic HTML structure based on the files and folders in your website.
+
+To do this, Vowel distinguishes between evergreen pages and ephemeral pages. A page with a `date` property is considered ephemeral, so it is excluded from the navigation and sitemap.
+
+Vowel will automatically create a multi-level nav, with one level for each parent folder for the current page.
+
+Vowel will create a full side navigation that displays all evergreen pages.
+
+# Frontmatter
+
+Reserved properties
+
+- `title`: Page title
+- `image`: Page image
+- `description`: Page description
+- `date`: Date published
+- `breadcrumb`: Short identifier for the page
+- `toc`: Optionally display a table of contents
+
+Vowel will attempt to impute the type of each frontmatter property. Imputed types include:
+
+- Links (Will generate a link preview)
+- Images (will display the image)
+- Date (will render a pretty date in a `time` element)
+
+You can also use lists and objects in frontmatter.
+
+# Markdown
+
+Vowel comes loaded with GFM (Github-flavored Markdown):
+
+```
+## Autolink literals
+
+www.example.com, https://example.com, and contact@example.com.
+
+## Footnote
+
+A note[^1]
+
+[^1]: Big note.
+
+## Strikethrough
+
+~one~ or ~~two~~ tildes.
+
+## Table
+
+| a | b  |  c |  d  |
+| - | :- | -: | :-: |
+
+## Tasklist
+
+* [ ] to do
+* [x] done
+
+```
+
+Along with all standard Markdown, Vowel also allows the following special elements:
+
+## Rich link previews
+
+Paste a URL on its own line (e.g. `https://example.com`).
+
+## Internal link previews
+
+Paste a relative path to a page (e.g. `/about`).
+
+The link will be rendered as an `article` element with a class representing the linked path (e.g. `page-blog-hello-world`).
+
+## Page lists
+
+A relative path to a folder with a `count` parameter (e.g. `/blog?count=2`). This will exclude the `home.md` file for the folder. In this example, it would return the `/blog/hello-world.md` file but not `/blog/home.md`.
+
+The page list will order pages first by date in reverse chronology (newest to oldest) and then alphabetically (a to z).
+
+The list will be rendered as `article` elements (see above) in a `section` element. The `section` element will have a class representing the folder path (e.g. `folder-blog`).
+
+## Headings
+
+If your document starts with an `h1` (`#`) and has no `title` property, the `h1` will be used as the meta title.
+
+If your document includes `h1`s after the title, all headings will be demoted one level (`#` to `h2`, `##` to `h3`).
+
+## Description
+
+If your document doesn't include a `description`, a meta description will be extracted from the text.
+
+## Notes
+
+Highlight information with note boxes:
+
+```
+:::tip
+Use `tip` for power-ups.
+:::
+
+:::note
+Use `note` for good-to-know information.
+:::
+
+:::important
+Use `important` to help guide your user down the right path.
+:::
+
+:::warning
+Use `warning` to help your user avoid the wrong path.
+:::
+
+:::caution
+Use `caution` to alert the user before they perform a destructive action.
+:::
+
+```
+
+:::tip
+Use `tip` for power-ups.
+:::
+
+:::note
+Use `note` for good-to-know information.
+:::
+
+:::important
+Use `important` to help guide your user down the right path.
+:::
+
+:::warning
+Use `warning` to help your user avoid the wrong path.
+:::
+
+:::caution
+Use `caution` to alert the user before they perform a destructive action.
+:::

package/docs-source/docs/settings.md

@@ -0,0 +1,4 @@
+---
+title: Documentation
+breadcrumb: Docs
+---

package/docs-source/docs/styling.md

@@ -0,0 +1,34 @@
+---
+title: Styling
+description: Add styles to your website.
+---
+
+Vowel allows styling through themes and vanilla CSS.
+
+## Themes
+
+Vowel includes a default theme, but you can disable this in your root `settings.md` file:
+```
+theme: none
+```
+You also have two other themes available:
+- `reset`: A classic CSS reset
+- `typography`: A classic CSS reset, plus some basic text styling
+
+## CSS
+
+Create an `assets/styles.css` file for your styling. We recommend using a style framework like Pico or Open Props. You can simply download their stylesheet and either copy-paste it into your own or include it in `assets/` and `import` it into `assets/styles.css`.
+
+For some inspiration on how to style semantic HTML, check out Swyx's [Spark Joy repository](https://github.com/swyxio/spark-joy).
+
+:::tip
+
+You can combine a theme with your own CSS. Feel free to use the `reset` or `typography` theme as a starting point and build from there.
+
+:::
+
+:::warning
+
+This project is still in development, so the generated markup is likely to change quickly and without warning, which will likely affect your styles.
+
+:::

package/docs-source/docs/taxonomies.md

@@ -0,0 +1,37 @@
+---
+title: Taxonomies
+description: Create tags, categories, and authors.
+---
+
+If the key for a frontmatter property matches a folder at the root of your project, Vowel will attempt to treat it as a taxonomy and link to the respective page.
+
+For instance, in this folder structure:
+
+```
+.
+├── home.md
+├── design.md
+├── recipes.md
+└── category/
+    ├── inspiration.md
+    └── lifestyle.md
+```
+
+You can write the following frontmatter in `design.md`:
+
+```
+---
+title: Design
+category: inspiration
+---
+```
+
+Vowel will render the property as a link to `/category/inspiration`.
+
+Then, in `category/inspiration.md` (or anywhere) you can display all inspiration posts with a post list:
+
+```
+/?property=category.inspiration
+```
+
+This allows you to create author pages, category pages.

package/docs-source/home.md

@@ -0,0 +1,42 @@
+# Home
+
+Vowel is a very simple Markdown- and CSS-based website generator.
+
+:::tip
+
+Start editing this page with one click by [opening it on StackBlitz](https://stackblitz.com/~/github.com/samlfair/vowel-site?file=home.md).
+
+:::
+
+To try Vowel out on your own computer, `cd` into a directory of markdown files and run:
+
+```
+npx -y -p svelte@next -p vowel@latest npx vowel
+```
+
+(This `npx` command forces the Svelte 5 peer depedency, without which the app will throw an error.)
+
+![A woman dancing](https://littlefair.imgix.net/florence-tango.jpeg?width=2048&auto=format%2Ccompress) Here's a photo
+
+Vowel is a minimal website framework for developers who love to write CSS and read RSS.
+
+> Here's a lovely block quote.
+
+Vowel will generate a feature-rich HTML website from a directory of markdown files. The output is plain HTML. You can style it however you want with your own CSS.
+
+:::warning
+
+This project is still in early development. There are many bugs and the API is changing quickly.
+
+:::
+
+Vowel is created by Sam Littlefair. If you have questions or comments, [reach out to me on Twitter](https://twitter.com/samlfair).
+
+
+# Features
+
+/$features?count=25
+
+# Try it
+
+/docs

package/docs-source/roadmap.md

@@ -0,0 +1,98 @@
+---
+description: What's planned.
+---
+
+# Roadmap
+
+## MVP
+
+- [x] Add all element types supported in Obsidian to markdown
+- [x] Add rich link previews
+- [x] Add RSS
+- [x] Add robots.txt
+  - [x] AI
+  - [x] Search
+  - [x] Image
+- [x] Typing
+- [x] Add sitemap
+- [x] Make taxonomies linkable in frontmatter (if a corresponding folder exists)
+- [x] Add header metadata (meta tags)
+- [x] CSS handling
+- [x] Favicon handling
+- [x] Docs
+- [x] Build action
+
+## V2
+
+- [x] Images as `<figure>`s
+- [x] Frontmatter interpolation (title and description)
+- [x] CSS default
+- [x] Better favicon and styles handling
+- [x] Ignore README files
+- [x] Include breadcrumbs in page titles
+- [x] Add hidden routes (`$`)
+- [x] Image alt text
+- [x] Deploy action (Vercel)
+- [x] Add anchor links for headings
+- [x] Figure out how to stop components from remounting on every change
+- [x] Demote headings global option (headings are now demoted intelligently)
+- [x] Taxonomy lists
+- [x] ~~Strikethrough~~
+- [x] Checklists
+- [x] GitHub-style notes
+- [x] Footnotes
+- [x] Better create/delete handling in HMR
+- [x] Disable default styles option
+- [x] Better theme CSS handling
+- [x] Create style reset theme
+- [x] Debug settings page HMR (temporary fix with full-page refresh)
+- [x] Fix checklist boxes
+- [x] Handle SVGs properly
+- [x] Slogan in homepage `<title>`
+- [x] Prioritize `title` and `h1` for meta title
+- [x] Prioritize `title` over `h1` for thumbnails
+- [x] Tables of contents
+- [x] Add a default 404 page
+
+## V3
+
+- [ ] Fallback homepages
+- [ ] Date format customizing
+- [ ] Init CLI
+  - Option for destructive actions
+  - Create homepage
+  - Create CSS file
+- [ ] ::Mark::
+- [ ] Frontmatter interpolation (image)
+- [ ] Add more header metadata?
+- [ ] Define folder settings
+  - [ ] Title
+  - [ ] Breadrumb
+- [x] Define special page properties
+  - [x] Title
+  - [x] Description
+  - [x] Meta image
+  - [x] Date
+  - [ ] Modified date
+  - [ ] Tags
+  - [ ] Author/Authors
+- [ ] Make file names kebab-cased for URLs and links
+- [ ] Code highlighter
+- [ ] Add in-browser search
+- [ ] Make RSS optional
+- [ ] Pagination
+
+## Wish list
+
+- [ ] Automatic file creation
+- [ ] Image serving and optimization
+- [ ] GUI
+- [ ] More deploy actions
+- [ ] Optional JSON interactivity (ratings, comments, SubPubHub)
+- [ ] Redirects
+- [ ] Advanced markdown
+  - [ ] Highlight
+  - [ ] Sanitize
+  - [ ] Mermaid
+  - [ ] Math
+  - [ ] Wikilinks

package/docs-source/settings.md

@@ -0,0 +1,12 @@
+---
+title: Vowel
+slogan: The easiest way to code a website
+breadcrumb: Home
+domain: 'https://getvowel.com'
+author: Sam Littlefair
+icon: 🔥
+robots:
+  google: true
+  google_images: true
+  ai: true
+---

package/extractDate.js

@@ -0,0 +1,83 @@
+/**
+ * @param {string} text
+ */
+function extractDate(text) {
+  const dateRegex = /(?:\b(?<first_segment>(?<first_MMM_or_MMMM>January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sept|Sep|Oct|Nov|Dec)|(?<first_YYYY>\d\d\d\d)|(?<first_do>(?:\d|[0-3]\d)(?:st|nd|rd|th))|(?<first_dd_or_MM_or_yy>[0-3]\d)|(?<first_d_or_M>\d))(?<first_delimiter>\.| |, |\/|-)?)(?:\b(?<second_segment>(?<second_MMM_or_MMMM>January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sept|Sep|Oct|Nov|Dec)|(?<second_YYYY>\d\d\d\d)|(?<second_do>(\d\d)(:?st|nd|rd|th))|(?<second_dd_or_MM_or_yy>[0-3]\d)|(?<second_d_or_M>\d))(?<second_delimiter>\.| |, |\/|-)?)(?:\b(?<third_segment>(?<third_MMM_or_MMMM>January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sept|Sep|Oct|Nov|Dec)|(?<third_YYYY>\d\d\d\d)|(?<third_do>(\d\d)(?:st|nd|rd|th))|(?<third_dd_or_MM_or_yy>[0-3]\d)|(?<third_d_or_M>\d)))(?<time>(?<time_delimiter>T|\ | at )(?<H_or_HH>[0-2]?\d):(?<MM>[0-6]\d)(?::(?<SS>00))?(?:\.(?<SSS>\d\d\d))?(?<Z>Z|(?:\+(\d\d):(\d\d)))?(?<meridiam_indicator>am|pm)?)?/i
+
+  const dateMatch = dateRegex.exec(text)
+  if(!dateMatch) return
+
+  const data = {
+    rawDate: dateMatch[0],
+    year: null,
+    month: null,
+    day: null,
+    hours: null,
+    minutes: null,
+    seconds: null,
+    meridiam_indicator: null,
+    timezone: null
+  }
+
+  const { groups } = dateMatch
+
+  const knownYear = groups.first_YYYY || groups.second_YYYY || groups.third_YYYY
+  const knownMonth = groups.first_MMM_or_MMMM || groups.second_MMM_or_MMMM || groups.third_MMM_or_MMMM
+  const knownDay = groups.first_do || groups.second_do || groups.third_do
+  const firstUnknowns = groups.first_dd_or_MM_or_yy || groups.first_d_or_M
+  const secondUnknowns = groups.second_dd_or_MM_or_yy || groups.second_d_or_M
+  const thirdUnknowns = groups.third_dd_or_MM_or_yy || groups.third_d_or_M
+  const allUnknowns = firstUnknowns || secondUnknowns || thirdUnknowns
+
+  if (knownYear) {
+    data.year = knownYear
+    if (knownMonth) {
+      data.month = knownMonth
+      data.day = knownDay || allUnknowns
+    } else if (knownDay) {
+      data.month = allUnknowns
+      data.day = knownDay
+    } else {
+      if (firstUnknowns) {
+        data.day = firstUnknowns
+        data.month = secondUnknowns
+      } else if (thirdUnknowns) {
+        data.month = secondUnknowns
+        data.day = thirdUnknowns
+      } else {
+        return false
+      }
+    }
+  } else if (knownMonth) {
+    data.month = knownMonth
+    if (knownDay) {
+      data.day = knownDay
+      data.year = allUnknowns
+    } else {
+      console.warn("The date parser has encountered a ambiguous date with a long month and a short year (e.g. `2 June 13`). Rewrite the date in a standard format.")
+      return false
+    }
+  } else if (knownDay) {
+    console.warn("The date parser has encountered an ambigous date format with an ordinal date, a short month, and a short year (e.g. 5th 06/24). Rewrite the date in a standard format.")
+    return false
+  } else {
+    data.year = "20" + groups.first_dd_or_MM_or_yy
+    data.month = groups.second_dd_or_MM_or_yy || groups.second_d_or_M
+    data.day = groups.third_dd_or_MM_or_yy || groups.third_d_or_M
+  }
+  if (groups.time) {
+    const isPM = /pm/i.test(groups.meridiam_indicator)
+    data.hours = isPM ? Number(groups.H_or_HH) + 12 : groups.H_or_HH
+    data.minutes = groups.MM
+    data.seconds = groups.SS || 0
+    data.timezone = groups.Z
+  }
+
+  const time = groups.time ? `${data.hours}:${data.minutes}:${data.seconds}${data.timezone || ""}` : null
+  const dateString = `${data.year} ${data.month} ${data.day}${time ? " " + time : ""}`
+
+  return new Date(dateString)
+}
+
+export default extractDate
+