New Structure for Docs

[mlrawlings]

New Structure for Docs

Guides

• Rendering
  • server side rendering
• Syntax
  • tags
  • attributes
  • inline javascript
• Loops & conditionals
  • keys
• Custom Tags
  • macros? (rename to inline-tag?)
• State
  • input vs state
  • no-update?
• Styles
• Layouts & containers
• Events
  • listening
  • emitting
• Async & streaming
• Accessibility
  • :scoped
• Animations
• Importing helpers
• Transformers
• 3rd party DOM libraries
  • onMount
  • key + this.getEl
• Web Components
  • registering with html-elements.json
  • wrapping imperative apis
  • using marko in a web component
• Component communication
  • input down, events up
  • key + this.getComponent
• Component composition
• Peak performance
  • NODE_ENV
  • Profiling/Flame graphs
  • Pass in promises

Reference

• Compiler

  • API
  • AST Nodes & Builder
  • Compile Context
  • marko.json/marko-tag.json

• Components

  • structure
    • single-file
    • multi-file
    • split
  • variables
  • attributes
  • properties
  • methods
  • lifecycle

• Render API

[jasonmacdonald]

Looks like a good start. One thing I might add is more details about what options that are available through the marko.json and marko-tag.json files. The old docs for Marko 3, if I recall, had lots of info on this, but I find I often need to go into the Marko tag-lib source code to see what I can do with those files. There's a lot of power there, but little explanation on how to use it.

Glad to see Transforms in the list, along with compiler stuff. Those would have been my other suggestions.

[StarpTech]

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 Marko v5? How can we participate?

Thank you.

[DylanPiercey]

@StarpTech we have plans this year to improve the documentation and have started with some additional documentation recently on transclusion, new syntax and configuration. We will be continuing to improve the documentation throughout the year.

I'll try to answer most of your questions here for now:

How to enable SASS in lassojs?
Via a plugin and then in Marko you can just add the .scss extension, even in inline style blocks.

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 ?
We also want to move in the direction of more static assets which is part of the reason LassoJS is currently in maintenance mode. We will be working hard to ensure a similar level of support for other bundlers like Webpack and Rollup throughout this year which are better suited to this task.

How to prebuild static assets with lassojs?
At this point in time this is the best reference we have: https://github.com/marko-js/cli/tree/master/packages/prebuild/README.md.

When is content delivered to the browser? Even an empty class will mark everything as client and server code. This isn't obvious.
I agree this can be confusing, but as you say the current heuristic is if the component has a class or component.js or is under a component which has one of these. This is not the best heuristic and we have plans to improve the situation here but I don't have much to share just yet.

Who is using markojs in production? How much is it used at ebay?
Outside of eBay we have not been keeping track but have provided support to many small teams. Inside of eBay Marko is used quite heavily and is serving a large portion of our web frontend.

I faced with many outdated or read-only repositories with signal a bad state of the ecosystem. Many issues has to be cleaned up.
As I mentioned we are working on it, help is greatly appreciated in updating these!

What are the plans for Marko v5? How can we participate?
I've talked a bit about it here. But to give an additional update since then, we have completed the migration portion (for now). This means existing apps running Marko 3 syntax can automatically migrate a good portion of their code to Marko 4. We have also simplified the syntax for a lot of our core tags and deprecated some duplicate features. All of this is also automatically migratable using marko migrate.

The current syntax you see on the website is what will be supported in Marko 5. Our plan is for Marko 5 to have very minimal breaking changes aside from having to potentially reconfigure your bundler. Again it is primarily a rewrite of the Marko compiler on top of babel to allow us to leverage the babel ecosystem, become more future proof in terms of JS and also improve our tooling and integrations.

Marko 5 lives in the x repo and we hope to get out an alpha in the coming months.

[StarpTech]

Hi @DylanPiercey thank you very much for the detailed answer. I'm happy to see that markojs is on the right track.

How to prebuild static assets with lassojs?
At this point in time this is the best reference we have: marko-js/cli:packages/prebuild/README.md@master.

Yes, I did and it works great. What are the reasons to stop improving Lassojs? I thought it is the default bundler at ebay. You dropped it for webpack?

I faced with many outdated or read-only repositories with signal a bad state of the ecosystem. Many issues has to be cleaned up.
As I mentioned we are working on it, help is greatly appreciated in updating these!

Definitly, but this requrires active maintainers and for me it feels like that only a few people are active as a maintainer in the ecosystem of markojs. Soo many unanswered issues and unreviewed pull-request this doesn't look too inviting.

[DylanPiercey]

@StarpTech

What are the reasons to stop improving Lassojs?
See my comment here.

I thought it is the default bundler at ebay. You dropped it for webpack?
We have not dropped Lasso at all. We are currently investigating if webpack can meet our needs while also trying to ensure great integrations with all bundlers for Marko.

Soo many unanswered issues and unreviewed pull-request this doesn't look too inviting.
We are a small (but I think growing) community. We have plans to improve the Marko ecosystem that I think will attract new developers and we are doubling down on Marko this year. Hopefully we can bring on some new maintainers as well 😄.