feat(docs): version 2.0.0 + migration to starlight #207

casungo · 2024-09-16T00:28:53Z

Component / Package Name: docs

This PR contains:

Are tests included?

yes (bugfixes and features will not be merged without tests)
no

Breaking Changes?

yes (breaking changes will not be merged unless absolutely necessary)
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.

casungo · 2024-09-16T00:41:42Z

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:

Wait for 2.0 to be ready to be merged and update the docs accordingly.
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).

dan-smt · 2024-09-21T13:14:39Z

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.

casungo · 2024-09-21T14:40:10Z

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!

casungo · 2024-09-21T17:28:16Z

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.

dan-smt · 2024-09-22T10:24:14Z

@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?

shellscape · 2024-09-22T12:43:34Z

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.

sysmat · 2024-09-22T12:43:38Z

Doc at one place is better

shellscape · 2024-09-22T12:45:04Z

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

shellscape · 2024-09-22T13:05:40Z

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.

casungo · 2024-09-22T13:12:49Z

Perfect, seems good!

This reverts commit 7b7cf9e.

casungo · 2024-10-25T22:20:33Z

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 added 8 commits September 15, 2024 17:13

initial creation

3f9630d

moved content

cc019cd

v0.0.1

aeb36a6

getting there

7a286c9

Update changelog.svelte

48576f3

convert to mdx

a0a4a3f

removed svelte & tailwind & changelog

2a9005b

Update astro.config.mjs

1f102bf

casungo added 2 commits September 21, 2024 16:24

remove old code

bfa579f

move to apps/web

371068e

try to deploy + to import from docs/

7b7cf9e

casungo added 9 commits September 23, 2024 23:36

Revert "try to deploy + to import from docs/"

7a988b2

This reverts commit 7b7cf9e.

test symlink

26f8725

fix components + new component!

a8f0d6f

added 2.0 edits

aac4c00

small fixes

140fa0a

added banner + v2 upgrade guide

7d2fb9a

update components

7754d61

core

fe34f3b

getting started

d5b3eac

casungo added 25 commits October 25, 2024 20:23

rename

72fbfbe

rename pt2

d6885bd

Update background.mdx

5460321

Update body.mdx

d307328

Update butan.mdx

6ef4dcf

Update button.mdx

561bef4

Update code.mdx

49abf6b

Update colorscheme.mdx

d4bad20

Update column.mdx

d10debf

Update conditional.mdx

c26fceb

Update container.mdx

4a096b8

Update font.mdx

02c5551

Update graph.mdx

5f00159

Update head.mdx

d90f6b3

Update heading.mdx

3d81a86

Update hr.mdx

cf201b9

Update html.mdx

5bdae16

Update img.mdx

758321a

Update link.mdx

275ea3e

Update markdown.mdx

7f46295

Update preview.mdx

e2468e7

Update row.mdx

ad42d6f

Update section.mdx

56bbd85

Update tailwind.mdx

7c69452

Update text.mdx

904bc7e

casungo added 4 commits October 29, 2024 17:04

Update package.json

1771175

added badges

3e7caea

theme, added font also

c075276

modifed logos so its more readable. also re-exported all of them

93f31de

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docs): version 2.0.0 + migration to starlight #207

feat(docs): version 2.0.0 + migration to starlight #207

casungo commented Sep 16, 2024

casungo commented Sep 16, 2024 •

edited

Loading

dan-smt commented Sep 21, 2024

casungo commented Sep 21, 2024

casungo commented Sep 21, 2024

dan-smt commented Sep 22, 2024 •

edited

Loading

shellscape commented Sep 22, 2024

sysmat commented Sep 22, 2024

shellscape commented Sep 22, 2024

shellscape commented Sep 22, 2024

casungo commented Sep 22, 2024

casungo commented Oct 25, 2024

feat(docs): version 2.0.0 + migration to starlight #207

Are you sure you want to change the base?

feat(docs): version 2.0.0 + migration to starlight #207

Conversation

casungo commented Sep 16, 2024

Component / Package Name: docs

Description

casungo commented Sep 16, 2024 • edited Loading

dan-smt commented Sep 21, 2024

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.

3. Current theming should also be applied to starlight.

casungo commented Sep 21, 2024

casungo commented Sep 21, 2024

dan-smt commented Sep 22, 2024 • edited Loading

shellscape commented Sep 22, 2024

sysmat commented Sep 22, 2024

shellscape commented Sep 22, 2024

shellscape commented Sep 22, 2024

casungo commented Sep 22, 2024

casungo commented Oct 25, 2024

casungo commented Sep 16, 2024 •

edited

Loading

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.

dan-smt commented Sep 22, 2024 •

edited

Loading