---
# System prepended metadata

title: Marko Documentation (tags-api)

---

# Marko Documentation (tags-api)

* [gist/mlrawlings/c12c976522344d41d47bcf8b46990101](https://gist.github.com/mlrawlings/c12c976522344d41d47bcf8b46990101)
* [marko-js/marko#874](https://github.com/marko-js/marko/issues/874)

Cross-pollination with URLs across diataxis boundaries

# `/docs` entry page

Should have a brief explanation of the top-level sections so people can understand what we're even doing with the diataxis thing

"If you're ${levelOfExperience}, start here"

Landing pages for each top-level section should probably explain _what_ it's about and who it's for, even if only in its `meta[name=description]`


# Tutorials

> I'm going to use markojs in production but as a beginner, I faced with following topics.
>
> - How to enable SASS in lassojs?
> - Instead to promote static sites only (marko-cli) we should also show the benefit of dynamic sites. How looks a basic app with a layout (header, footer, body), css preprocessor, prebuilds, deployment, babel, autoprefixer ?
> - How to prebuild static assets with lassojs?
> - When is content delivered to the browser? Even an empty class will mark everything as client and server code. This isn't obvious.
> - Who is using markojs in production? How much is it used at ebay?
> - I faced with many outdated or read-only repositories with signal a bad state of the ecosystem. Many issues has to be cleaned up.
> - What are the plans for [future Marko versions]? How can we participate?
>
> ---[marko-js/marko#874 comment 466802495](https://github.com/marko-js/marko/issues/874#issuecomment-466802495)


* Intro
    * Get Started
        * Try Online
        * CodeSandbox? (we should only provide one path, if this is a tutorial)
        * `marko serve`
    * Anatomy of a Marko Tag
        * Tag Name (start + end tags)
        * Vars
        * Params
        * Attributes
        * Pseudo-attributes
        * Nested body content
    * Variables & Text Interpolation
        * Escaping
* Styling & CSS
    * `<style>`, `style {}`, `style=""`, `style={}`
    * `<tag#id.class.other-class>` shorthands
    * `class=""`, `class=[]`, `class={}`
    * Using CSS preprocessors
* State & values
    * `<let>`
        * Snapshot of the initial value
        * Mutable references, immutable values
    * `<const>`
        * Immutable references, computed values
        * Observing time, self-referencing reducer pattern
            * [rxmarbles.com/#scan](https://rxmarbles.com/#scan)
* Loops & conditions
    * `<for>` (`[of]`, `[in]`)
    * Keys?
    * `<if>`, `<else>`
* Effects
    * `<lifecycle>`
    * `<effect>`
    * DOM refs (`key`?)
* Components
    * Discovery
        * `/components/`
        * import Component from '<component>'
    * Inline components (`<tag>`)
    * Communication with Children
        * Attributes
        * Arguments?
    * Communication with Parent
        * Events
        * Parameters
        * Return Values
    * Communication with Siblings/Cousins
        * Lifting state up
        * Using custom body content to make the tree shallower
        * `<context>`
    * Third-Party components
        * Usage
        * Link to Publishing Guide
* Body content ("nested content")
    * Existing `renderBody` page, with better examples
    * Type (markup, text, script) (fix the parser)
    * Parameters
* Promises
    * `<async>`/`await`
    * Fetching data
    * Streaming SSR
* Errors
    * `<try>`/`<@catch>` (and rethrowing from `<@catch>`)
    * Recovering from errors (especially while streaming)
* Testing
    * `@marko/testing-library`
    * `@marko/fixture-snapshots`
    * `@marko/jest`
* Migrations
    * `marko migrate`

## Advanced Tutorials

> @dylanpiercey: I think all of these [existing] sections are written as tutorial-like:
> 
> Conditionals and lists
> Custom tags
> State
> Styles
> Events
> Body content

* Color picker
* TodoMVC?
* HackerNews?
* Writing a Utility Component
    * MediaQuery/Online/etc.
* Zero to hero (Intro to webdev with Marko)
    1. Basic HTML
    1. Adding `<style>`
    1. Pages
    1. Stylesheets
    1. JavaScript
    1. HTTP Server
        1. Installing Node.js
        1. `npm install serve`
        1. Leaving off `.html`
        1. Live Reloading
    1. Deploying
        * Vercel? Cloudflare workers?
        * Marko Build
    1. Marko Serve
        * Marko is a near superset of HTML - rename your files
            * `npx laren "./**/*.html" "(f) => f.replace('.html', '.marko')"`
        * Live Reloading
    1. Sharing code using components
    1. State
    1. Using npm modules
    1. Persistent Data
        * Airtable? Google sheets? Firebase? Something else?
        

# How-to Guides

* Integrating with embeds/analytics/other libraries/miscellaneous DOM mutators
    * onMount
    * key + this.getEl
* Troubleshooting streaming
* Layouts (aka page components)
    * How to avoid `state` in components containing `<html>` or `<body>`
* Integrating into an existing Node.js project
* Integrating into an existing non-Node project (like what, Java?)
* Making Marko work with Content-Security Policies
* Publishing components
    * `marko.json`
    * Best practices
    * Storybook?
* Writing a migrator
* Writing a translator
* Choosing between `<let>` and `<const>`
* Streaming with Node’s HTTP/2
    * https://github.com/marko-js/marko/issues/1273
* Using Marko with HTML consumers stricter than browsers
  - https://github.com/marko-js/marko/issues/1432#issuecomment-668698247
* Optimizing performance
    * Optimizing client-side JS size
    * NODE_ENV
    * Pass in promises
    * Streaming performance
    * Profiling (flame-graphs)
        * server-side
        * client-side
    * `<cached-fragment>`
    * Reducing hydration data?
        * sortable `<table>`, without shipping JS to hydrate all the individual cells
* Using Web Components
    * [marko-js/marko#862: Docs for using custom elements with Marko](https://github.com/marko-js/marko/issues/862)
    * Consuming in Marko
        * Registering with `html-elements.json`
    * Using Marko in a web component
        * Exporting
    * Wrapping imperative apis
* Fixing form resubmission dialogs: [the `POST`→redirect→`GET` pattern](https://en.wikipedia.org/wiki/Post/Redirect/Get)


# Explanations

Concepts in-depth/deep-dives

- Animations
- Accessibility
    - scoped `id`s
    - out-of-order rendering
    - controlled component pitfalls
- Use-cases for `<await>`
  - blocking streams, like search results
  - out-of-order streaming with small timeouts, like recommended products
  - that one `<datalist>` example for search suggestions?
  - optional rendering?
  - error-handling: mark stream as damaged vs. "whatever it's fine"
* Single-file vs. multi-file components
* Split components
* How compilation works
    * Parser
        * Tags can change parse mode
    * Building the AST
        * Babel patches
    * Migrate
    * Transform
    * Translate
    * Generate
* How streaming works
    * Deep dive into async writer
    * `<html-chunk>`/`<html-chunk-slot>`
* How hydration works
    * valav
* How DOM updates work
    * Signals
        * Async computations

("evergreen blog posts"? integrations with specific technologies? Search engine bait? Troubleshooting HTTP Streams, problems we know people have) FAQ? Help? Check Before You StackOverflow? Troubleshooting?


# API Reference

Have the examples in the API reference have an output pane (but only a link to edit it, because otherwise the perf hit would be excruciating)

* [Browser support](https://github.com/marko-js/marko/issues/785)?
* Syntax
    * Glossary
        * Tag  
          - `<tagName attributeName=attributeValue></tagName>`  
          - Like HTML, **tags** are made of [tag name]s, [start tags], [end tags], and [attributes]. You can [nest content] between the start and end tags, or close the tag immediately.
        * Dynamic tag
        * Self-closing tag
        * Attribute
            * Attribute name
            * Attribute value
            * Boolean attribute
        * Pseudo-attribute
        * Attribute tag
        * Text content
        * Dynamic text/HTML content
        * HTML Character references and JS escapes
        * Comments
        * Element
        * Concise Mode
    * Exceptions to “Marko is a superset of HTML”
        * Unquoted attribute values
            * Probably don’t use Marko to make HTML emails
        * Javascript strings vs HTML strings
            * `<input pattern>`
            * Escaping
        * Tag namespaces (technically XML, not HTML)
            * `<fb:login-button>`
            * Probably don’t use Marko to generate RSS/Atom/etc.
        * Attribute namespaces
            * `<use xlink:href>`
        * Comments and `<html-comment>`
            * `<!--#include -->` (SSI)
    * Concise mode
    * TypeScript
* Single-file components & multi-file components (“vs.” would be in Guides)
* `marko-tag.json` & `marko.json` (“vs.” would be in Guides)
* Core tags
* Class components
    * `<component>`?
    * `<tag>`?
* Widgets?
    * `<widget>`?
* Rendering APIs
* Compiler
  - API
  - AST Nodes & Builder
  - Compile Context
  - `marko.json`/`marko-tag.json`
* Taglibs
* Bundler integrations
    * Webpack
    * Rollup
    * Vite


# Marko For 𝑋 Developers



* For React devs
    * [🏚 gist/mlrawlings/921bfcd60b8cc4e1d5ec3964949403ec](https://gist.github.com/mlrawlings/921bfcd60b8cc4e1d5ec3964949403ec)
* For Vue devs
* For Angular devs
* For Marko 3/4/5 devs
* For Solid devs 🤨
* For PHP devs

# Showcases/Example Apps

More involved codebases that demonstrate how Marko works, but without guided handholding

- [7 GUIs](https://eugenkiss.github.io/7guis/tasks/)
- Programmable Faucet from Clipper
- `vercel/ecommerce` ⑂ `marko/ecommerce-but-fast`


# Community

* Team & Contributors
    * Core Team
        * International criminal Michael Rawlings
        * The Big D. Pierce
        * That guy with the skull avatar
        * 2 MIA guys we allegedly have coming up
    * Emeritus
        * [_Our Founder_](https://cdn.contexttravel.com/image/upload/c_fill,q_60,w_2400/v1572375264/production/product_image/image__1572375264.jpg) Patrick Steele-Idem
        * Philip Gates-Idem
        * Austin Kelleher
        * Martin Aberer
        * Ryan “Solid” Solid
    * All Contributors
        * (pull from github) (how are they sorted?)
* Who uses Marko?
    * `awesome-marko` list of projects (this has been proposed before)
    * eBay
    * 🏚 [docs.google.com/document/d/1a9xrGwwT0zoLc9jO0J7ueGLtnAEdLFef2Fg6nbli2-8](https://docs.google.com/document/d/1a9xrGwwT0zoLc9jO0J7ueGLtnAEdLFef2Fg6nbli2-8)
    * Not Kroger
    * Not RedBubble
* Contributing
* RFC/Proposal process
    * Example processes:
        * [supercollider/rfcs](https://github.com/supercollider/rfcs)
        * [rust-lang/rfcs: RFCs for changes to Rust](https://github.com/rust-lang/rfcs)
        * [swift-evolution/process.md](https://github.com/apple/swift-evolution/blob/master/process.md)
    * Statuses
        * Accepted
        * Provisional (basic idea accepted, but details pending)
        * Rejected
        * Withdrawn (by the author, or from inactivity/disinterest)
* Core Team meetings
    * Livestream
    * Everyone is invited
* Speaker resources (Giving a talk on Marko? We can help!)
    * Logos/presskit
    * Slide templates
    * Speaking Tips
    * Order Marko swag
    * Schedule a practice talk
* Articles
  * [**The Future of Marko - Oct. 2017**](https://tech.ebayinc.com/engineering/the-future-of-marko/) \
On joining the JS Foundation (now the OpenJS Foundation)

  * [**Why is Marko Fast? - May 2017**](https://hackernoon.com/why-is-marko-fast-a20796cb8ae3) \
Optimization strategies used by Marko

  * [**Server-Side Rendering Shootout - Jan. 2017**](https://hackernoon.com/server-side-rendering-shootout-with-marko-preact-rax-react-and-vue-25e1ae17800f) \
Comparing SSR performance across frameworks

  * [**Rediscovering Progressive HTML Rendering with Marko - Dec. 2014**](https://tech.ebayinc.com/engineering/async-fragments-rediscovering-progressive-html-rendering-with-marko/) \
Benefits of making early flushing a first-class citizen

* StackOverflow (`#marko` tag, ask a question, …?)
* [Discord](https://discord.gg/marko)
* GitHub
* Roadmap