# 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