diff --git a/README.md b/README.md
index c85b5fc982972850bcc85a0fc44ba4138059c4dc..b476c00767b4b00d78f3f60c19df71bbd43addc7 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,7 @@ meta:
 
 # ${meta.title}
 
-i'm a catgirl and i love to **meow**! meow meow meow! 
+i'm a catgirl and i love to **meow**! <rainbow-text>meow meow meow!</>
 
 ```ts
 function doMyFavoriteThing() {
@@ -73,11 +73,12 @@ i love being alive. ${'<3'} from ${new Date().getFullYear()}.
 
 ## Install
 
-Markodown is distributed on [NPM](http://npmjs.com/markodown) and
+Markodown is distributed on [NPM](https://npmjs.com/package/markodown) and
 [JSR](https://jsr.io/@clo/markodown). The compiler runs anywhere JS+WASM runs.
 
 ```sh
 npm i markodown
+# or
 npx jsr add @clo/markodown
 ```
 
@@ -97,6 +98,7 @@ export default defineConfig({
       // optionally wrap all markdown files in a layout, this component is
       // given a list of headers to construct a table of contents.
       layoutImport: "../tags/markdown-layout.marko",
+      // ...more customization options are well-documented in the types.
     }),
   ],
 });
@@ -104,7 +106,7 @@ export default defineConfig({
 
 ## Components
 
-All Marko features, such as [tag resolution], [attribute tags],
+All Marko features are supported, such as [tag resolution], [attribute tags],
 [class shorthands], and template expressions. This makes it so much easier to
 add complex content to your pages.
 
@@ -130,7 +132,7 @@ You can use Markodown to write blogs and long documents, then extract a table of
 contents. This is done with two mechanisms.
 
 - `layoutImport` which wraps the entire document in a component, which is given
-  three attributes.
+  three attributes. (see typescript types on the plugin / `transform` function)
   - `content`: the rendered content.
   - `module`: the module namespace for the compiled Markodown file.
   - `outline`: an array of `Heading` objects.
@@ -212,7 +214,8 @@ this paragraph gets wrapped in a `<p>` tag!
 
 ## Static Statements
 
-Define module-level functions and variables.
+You can define module-level functions and variables,
+[same as you can in Marko](https://markojs.com/docs/reference/language#statements).
 
 ```
 static function sort(items: string[]) {
@@ -229,9 +232,9 @@ Note that this means writing a paragraph starting with the lowercase words
 ```
 # All About RSC
 
-\server components are stupid. (markdown backslash)
+\server components are a bad idea. (markdown backslash)
 
-${"server"} components are stupid. (template literal)
+${"server"} components are a bad idea. (template literal)
 
-Though you can say import as long as its not the first item.
+Though you can say import as long as it's not the first item.
 ```