Documentation Updates

[sastan]

I have re-structured the documentation to have a good starting point to provide a better "on-boarding": https://twind.dev/docs/

I have splitted the documentation in to two parts:

1. Handbook: more like a tutorial and some "How To" – sourced from the docs/ folder (see docs/pages.json)
2. API: reference describing the machinery – sourced from README.md in src/ (for example src/shim/README.md)

The website is currently updated on every push to main. Later I would like to only update the website on releases to have a stable documentation for a release that is not mixed with upcoming features.

What needs to be done?

• docs/getting-started/styling-with-twind.md: use a tutorial approach – other parts of "Getting Started" may need some review to
• Empty Pages
  • docs/getting-started/quicksheet.md
  • docs/getting-started/best-practices.md
  • docs/recipes/README.md
  • docs/recipes/use-with/vue.md
  • docs/migrate-from/tailwindcss.md
  • docs/migrate-from/twin-macro.md
  • docs/faqs/README.md
  • docs/release-notes.md
  • inline css for email: Parse classNames to inline styles.  #96 (comment)
• create a theme for typedoc using twind

I'm sure there is a lot more to improve. I hope that some native speakers may pick some of the tasks and provide PRs for these.

You can build the website locally using: yarn typedoc && open website/docs/index.html

/cc @tw-in-js/contributors

[just214]

I'm happy to help with the documentation. I have a quick reference that I could clean up and commit. I'll also take a closer look at the docs and see where I think my efforts would be most useful. Once I have a better idea, I'll comment here first to make sure I don't duplicate anyone's efforts.

[sastan]

I'll post a comment here when I start to work on a page.

[just214]

I'm still mulling over the docs proposal/changes, but I had a couple thoughts:

Has there been any consideration for documentation tools other than Typedoc? Have you looked at or considered https://docusaurus.io/? I've used it in the past and really enjoyed it. There would be some trade-offs (like mdx vs md (React), no translations yet, no apparent JsDoc support), but there is also some really nice tooling around it. One big one is their Algolia integration, which is painless and free for open-source projects (https://www.algolia.com/for-open-source)

But, I do see some magical things going on in the Twind markdown files and I am guessing that Typedoc might be taking care of converting JSDoc comments. And, those things might be too important or useful to walk away from and that is understandable if so.

Anyways, not trying to rock the boat and I’m happy to help with Typedoc if that is the direction…just wanted to mention this.

Here is a project in Docosaurus 2 that I made a while back if you’d like to check it out for reference:

https://www.tsx.guide/introduction/welcome

And, here is an example of a page where I embedded a Typedoc-generated site in an Iframe:

https://www.tsx.guide/resources/react-types-explorer

[sastan]

Has there been any consideration for documentation tools other than Typedoc?

I thought about using nextjs, wmr and docusaurus but at that moment it was too much overhead for me. We already had typedoc in place for the API and adding a plugin to add pages seemed a lot easier.

Have you looked at or considered https://docusaurus.io/? I've used it in the past and really enjoyed it.

We use it at work and I like it too.

There would be some trade-offs (like mdx vs md (React), no translations yet, no apparent JsDoc support), but there is also some really nice tooling around it. One big one is their Algolia integration, which is painless and free for open-source projects (https://www.algolia.com/for-open-source)

Typedoc includes a search but I do not know if markdown files are searchable.

But, I do see some magical things going on in the Twind markdown files and I am guessing that Typedoc might be taking care of converting JSDoc comments. And, those things might be too important or useful to walk away from and that is understandable if so.

That was the final kicker for me. We can link to API doc of a method or a module using helpers. It works for pages as well.

Anyways, not trying to rock the boat and I’m happy to help with Typedoc if that is the direction…just wanted to mention this.

Please rock the boat! Your input is always welcome.

Here is a project in Docosaurus 2 that I made a while back if you’d like to check it out for reference:

https://www.tsx.guide/introduction/welcome

And, here is an example of a page where I embedded a Typedoc-generated site in an Iframe:

https://www.tsx.guide/resources/react-types-explorer

Very nice.

---

I want to reach different audiences with the docs:

1. Getting started, Advanced: a guide /walk through
2. Recipes, Module index page: How to styles with a lot of examples
3. API doc: dig deeper into what is possible

Typedoc allows to use a own theme. I imagined we can create a own theme using twind.

I chosed typedoc because it currently checks all the boxes and we are already using it. But I'm open to use a different tool. For the moment I want focus on the content. I barely have time for that.

[just214]

Thanks for the meaningful response! After reading your comments, it makes perfect sense to me now why you stuck with Typedoc, at least for now.

And, I do agree that content should be priority, especially with the swiftly evolving changes. The content could also help inform some decisions about the tech stack down the line.

[just214]

FAQ regarding shim: When does it make sense to use the shim? Are there downsides and should explicit tw calls be preferred when possible?

[sastan]

FAQ regarding shim:
When does it make sense to use the shim?

As a drop-in replacement for tailwindcss + purge, for playing around or prototyping, online editor without need for a build step

Are there downsides and should explicit tw calls be preferred when possible?

There is a runtime impact as Twind needs to parse the whole class attribute, basically node.setAttribute('class', tw(node.getAttribute('class')))'. For mostly static sites or apps this should not be a problem. For highly dynamic sites/apps tw should be preferred. But to be honest we have to measure the performance on real world apps to know for sure.

[just214]

I'd like to start working on a quick reference (cheatsheet), which would serve as a condensed version of the docs in a single document. I started a version for myself a while back, so I already have a pretty nice head start.

The basic outline that I have in mind is as follows:

• Useful Links (Twind docs, GitHub Repo, etc...)
• Main features of Twind:
  • For each feature:
    • A high-level explanation
    • A link to the corresponding website documentation
    • Minimal code examples
• Other useful information:
  • Lists: Twind directives, Inherited CSS properties, variants, etc.

If anyone has any thoughts or objections, I'd like to hear them. Otherwise, I'll get to work on it.

[sastan]

@gojutin This sounds great.

[just214]

I've been keeping a list of potential FAQs as they come to mind. I figure I'll go ahead and post them here in case anyone else is interested in seeing or discussing them. I'll continue to update this list as I go unless another format is preferred. I'm also happy to get in this into the docs once the details are ironed out.

A couple thoughts:

• There's countless ways that you could word these questions, and I opted for the "How do I...?" approach where it made sense to me. We could also go with more of a "Does Twind support raw CSS?" format. I think the key is to just try to stay consistent and fit as many useful keywords in the questions as possible.
• For some questions, I think a brief answer with a link to the appropriate docs might be all that is needed.

FAQS

• Does Twind work with XYZ framework or library? (Vanilla JS, TypeScript, React, Vue, Svelte, Solid, Angular, Web Components, React Native, Alpine, Next, Gatsby, etc...)
• Does Twind support dark mode?
• Does Twind maintain feature parity with Tailwind? (if it works in Tailwind, is it guaranteed to work in Twind?)
• Does Twind support TypeScript?
• How does Twind differ from Tailwind?
• How do I get started using Twind?
• How do I migrate my existing project to Twind?
• How do I write global styles in Twind?
• How do I write raw CSS in Twind?
• How do I override a style in Twind?
• How do I access a theme value in Twind?
• How do I use Twind with server-rendered (SSR) apps?
• When should I use the shim and are there any downsides?
• How do I know when to use tw vs. apply vs. lazy?
• Is there a Twind VSCode extension for syntax highlighting, style validation/linting, auto-completion, etc..?
• Does Twind have an online community?
• How do I contribute to this project?

[sastan]

Great list of questions. I totally agree with the wording and keeping the answers brief (maybe a short snippet) with links to the docs.

@gojutin Do you need help with some of the answers?

I may like to add these:

• What is the difference to twin.macro? (framework agnostic, ...)
• Why not just Tailwindcss? (no purging, our extensions, the shim)
• Isn't this like writing style attributes? (it's utiltity-first)
• But CSS-in-JS is slow? (is it, first rendering – SSR, shim)
• What about caching? (SSR)

I know the wording does not match and I do not have well-phrased answers for those.

[just214]

Thanks, I've combined our questions (and a couple more along the way) and tried to come up with wording that covers as many keywords as possible. I've also broken the list into categories (just for our reference), but the lines get blurry based on how you word the questions. (eg. "Does Twind support dark mode?" vs. "How do I use dark mode with Twind?")

General

• Why not just use TailwindCSS?
• What is CSS-in-JS?
• How does CSS-in JS perform? Is it slow?
• Is this the same as writing style attributes?
• Does Twind work with XYZ framework or library?
• Does Twind support TypeScript?
• Does Twind support dark mode?

Comparisons

• How is Twind different from TailwindCSS?
• Does Twind maintain feature parity with TailwindCSS?
• How is Twind different from twin.macro?
• How is Twind different from other CSS-in-JS solutions?

Usage

• How do I get started using Twind?
• How do I migrate my existing project to Twind?
• How do I write global styles in Twind?
• How do I write raw CSS in Twind?
• How do I override a style in Twind?
• How do I access a theme value in Twind?
• How do I use Twind with server-rendered (SSR) apps?
• How do I cache my Twind styles?
• When should I use the shim and are there any downsides?
• How do I know when to use tw vs. apply vs. lazy?

Tooling

• Is there a Twind VSCode extension for syntax highlighting, style validation/linting, auto-completion, etc..?

Community

• Does Twind have an online community?
• How do I contribute to this project?

[just214]

I'm happy to move the FAQs (no answers yet) to either a PR or into a GitHub project so that they are easier to collaborate on. A GitHub project has the added benefit of easy sorting to determine order, but I'm glad to do either. Or, any other ideas?

[sastan]

@gojutin Whoa! Great job.

If you create a PR and allow the maintainer (me) to edit the PR we can collaborate on that one. Other people can use the suggestion feature. Sounds good?

[just214]

I'm going to make an effort to at least start answering some of these before I submit a PR. I'm following the same format as the existing FAQ doc (detail, summary). I'll have it submitted by tomorrow and we can regroup from there.