jsx-email
jsx-email copied to clipboard
shellscape
feat(docs): version 2.0.0 + migration to starlight
Component / Package Name: docs
This PR contains:
- [ ] bugfix
- [ ] feature
- [ ] refactor
- [x] documentation
- [ ] other
Are tests included?
- [ ] yes (bugfixes and features will not be merged without tests)
- [x] no
Breaking Changes?
- [ ] yes (breaking changes will not be merged unless absolutely necessary)
- [x] no
Description
Hello, I'm creating this draft pull request so the progress of migrating to starlight is public. I created a new folder under apps/docs so that for now nothing is deleted an can be later migrated to another folder or something else. I had some issues with installing moon and linting so for now nothing is linted with the command and I had to suppress eslint errors because they were preventing me from committing my changes.
The current state of things is pretty good, the main parts of the docs are pretty much done. The things that are left to do are:
- [x] Wait for 2.0 to be ready to be merged and update the docs accordingly.
- [x] Re-write of some of the introduction/quick start. Since I only copy pasted the md files and fixed "graphical" things (for example the :::tip asides) some things are wrong, such as referencing the docs when the user is already reading them (eg. in the introduction).
Hey @casungo great work so far! I was chatting with @shellscape about this but looks like you beat me to it. Here are some notes from our conversation that should help you make this even better.
1. You can find the current vitepress docs under /apps/web, you should also probably change the PR so that the starlight docs replaces the code in this directory.
2. There are some include directives in the markdown files that import parts of other markdown files / and sometimes standalone components. There are also some symlinks, symlinks and starlight don't seem to work great right now, and starlight doesn't support the import directives at all.
Currently the repo is keeping docs under /docs for them to be easily accessible through github directly, and using a symlink to include it in the docs, you could have a similar system that references the docs markdown files to avoid duplication, while not turning /docs into mdx files, as those look a bit ugly since the import statements etc. stick around in githubs preview.
Here is what my approach would be:
apps/web/src/components/Install.mdx
import { Tabs, TabItem, Code } from '@astrojs/starlight/components';
## Install
Install the { props.type } from your command line
<Tabs>
<TabItem label="pnpm">
<Code code="pnpm add jsx-email" lang="sh" />
</TabItem>
<TabItem label="bun">
<Code code="bun add jsx-email" lang="sh" />
</TabItem>
<TabItem label="npm">
<Code code="npm add jsx-email" lang="sh" />
</TabItem>
<TabItem label="yarn">
<Code code="yarn add jsx-email" lang="sh" />
</TabItem>
</Tabs>
apps/web/src/content/docs/components/body.mdx
---
title: 'Body'
description: 'A JSX email component for using a React `Body` component to wrap email content'
---
import Install from "@components/Install.mdx"
import Body from "@docs/components/body.md"
<Install type="component" />
<Body />
apps/web/tsconfig.json
{
"extends": "astro/tsconfigs/strict",
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@assets/*": ["src/assets/*"],
"@components/*": ["src/components/*"],
"@docs/*": ["../../docs/*"]
}
}
}
I think the way starlight does things, the Header component doesn't need to be migrated. There are also tooltips that start with ::: tip that need to be converted to the starlight equivalent (Aside), this would be an mdx component, so this is something you might want to exclude from /docs and include in the components that import docs & other necessary components.
So, in short there's a bit of going through markdown files, and converting syntaxes that need to be done; also be vary of certain include statements that only include parts of other markdown files, that content will need to be copy pasted over.
3. Current theming should also be applied to starlight.
Feel free to ask for help if you need any.
Sure thing! Seems like a solid plan, will work on it in these days. Also would like to rewrite the https://samples.jsx.email/ webpage someday with Astro + daisyUI (+ Svelte if necessary :) ). I will also deploy the current state of this PR on cloudflare as a temporary webpage so everyone can see the progress being made, if that seems like a good idea!
While working on this, I wondered why there is a need for two folders for the documentation—one at the root of the project and another in apps/web. Wouldn't it be more efficient to consolidate all the information into a single location within apps/web? This way, there would be no need for importing from various files. Users looking for documentation could simply visit the website, or if they prefer, they could browse the repository directly under apps/web to find all the content in one place. Having two separate folders seems unnecessary.
@casungo to give you a quick response from our conversation... the reason for having a /docs at the root is so that people on github can easily find the docs without needing to dig much into the codebase, but with the mdx components now, some of the content (tips) would be under /apps/web, while the rest of the content is in /docs, so the split is getting not so pretty, maybe it could be better to do it the way you're proposing and symlink /docs to apps/web/src/content. @shellscape thoughts?
Also would like to rewrite the https://samples.jsx.email/ webpage someday with Astro + daisyUI (+ Svelte if necessary :) ). I will also deploy the current state of this PR on cloudflare as a temporary webpage so everyone can see the progress being made, if that seems like a good idea!
@casungo that sounds awesome. I totally welcome it.
maybe it could be better to do it the way you're proposing and symlink /docs to apps/web/src/content. @shellscape thoughts?
@casungo @dan-smt yeah I'm open to the symlink being reversed
I merged the v2.0.0 changes to main without releasing them. That should make it easier for this PR. Going to start working on docs in a temp directory on another branch, so that it doesn't conflict with the work here. I'll update manually once we get this PR in.
The final version has landed! Everything is fresh and new. you can preview the site at: https://jsx-email.pages.dev/ (temp site just to preview, will bring it down once everything is merged)
@casungo looks like the color theme dropped again. this is still something I want to do very badly 🙏