docs(theming): add theming reference to tutorialkit.dev #97

SamVerschueren · 2024-06-25T13:25:55Z

This PR adds a new theming section to https://tutorialkit.dev.

It probably needs some extra eyes to go through the document and tweak where needed.

While documenting, I also created additional PRs to tweak and improve the theming.

bolt-new-by-stackblitz · 2024-06-25T13:25:59Z

Run & review this pull request in StackBlitz Codeflow.

changeset-bot · 2024-06-25T13:25:59Z

⚠️ No Changeset found

Latest commit: 8e75d54

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

cloudflare-workers-and-pages · 2024-06-25T13:32:45Z

Deploying tutorialkit-docs-page with Cloudflare Pages

Latest commit:	`8e75d54`
Status:	✅ Deploy successful!
Preview URL:	https://da5700ec.tutorialkit-docs-page.pages.dev
Branch Preview URL:	https://docs-theming.tutorialkit-docs-page.pages.dev

View logs

cloudflare-workers-and-pages · 2024-06-25T13:58:06Z

Deploying tutorialkit-demo-page with Cloudflare Pages

Latest commit:	`eb24b17`
Status:	✅ Deploy successful!
Preview URL:	https://1506ecdc.tutorialkit-demo-page.pages.dev
Branch Preview URL:	https://docs-theming.tutorialkit-demo-page.pages.dev

View logs

SamVerschueren · 2024-06-25T14:04:05Z

docs/tutorialkit.dev/astro.config.ts

-      plugins: [starlightLinksValidator()],
+      plugins: [
+        starlightLinksValidator({
+          exclude: ['../guides/**/*'],


I think this is related to HiDeoo/starlight-links-validator#39.

sulco · 2024-06-25T18:58:29Z

This looks great! One thing that I think is still worth improving are the screenshots: looks like they are low resolution so when watching on a higher res screen, they looks blurred + the webp conversion creates some additional artifacts (see the screenshot).

If you don't have access to higher density screen, zooming in the page 200% should do the trick.

Probably not a blocker though;) so though having them nice and sharp would be good, we can fix it later, too

d3lm

Awesome work Sam! This looks great.

Here are some other thoughts I had while reviewing:

The screenshots seem to be blurry / low res on my end and we ought to fix those
Potentially we could re-organize some of the sections to improve the structure a bit but we can always do that later. Like I said, this is great and this is just a thought I had. For instance, we could group related elements together. We could have main sections like "Basic Customization" (Logo, Styling), "UI Elements" (Content, Callouts, Statuses, etc.), and "Interactive Components" (File Tree, Terminal, etc.).
We may wanna ensure all sections follow the same pattern of presentation. For example, not all sections have a brief description (I think I commented on the one where it was missing), an image (if applicable), and then the list of customizable tokens. Most section follow this pattern but not all. Also the style of the description of each varies.
Later down the road it may be helpful if we provide a bit more context on how these elements are used in the interface.

All of the above is not something we have to fix in this PR or fix at all. Just a couple of thoughts, and the docs and everything is something we have to work on iteratively anyways.

Again, overall this is amazing! Thanks for writing this page Sam!

docs/tutorialkit.dev/src/content/docs/reference/theming.mdx

Co-authored-by: Dominic Elm <[email protected]>

SamVerschueren · 2024-06-26T07:48:10Z

I'll try to improve some of the points you mentioned @d3lm. I think the screenshots being blury might have something to do with the fact I created them on my external screen. I think I need to create them on my laptop screen. It's annoying that the end result is different.

AriPerkkio

First thing that comes to mind when I started theming: It would be nice to have default theme.css file generated or available elsewhere so that I could directly change the variables there. Copy-pasting variable names from docs works but is a bit slow.

Nemikolh · 2024-06-26T09:57:17Z

@AriPerkkio do you think if we had a CLI command that generated a theme.css with all the variables and their current values that would be good enough?

Nemikolh

This is really good!! Good work on this! 🎉

AriPerkkio · 2024-06-26T10:04:43Z

@AriPerkkio do you think if we had a CLI command that generated a theme.css with all the variables and their current values that would be good enough?

Yes, something like this would work. Ideally the build process would output separate dist/theme.css that the actual production build uses. This CLI command could then simply either copy the file from dist or use Vite/Astro to emit the file in the root of the project. In this case there would be no need to maintain separate theme.css just for the CLI - it would be 100% the same file that production build uses.

d3lm · 2024-06-26T12:35:26Z

docs/tutorialkit.dev/src/styles/custom.scss

ℹ️ Updated these cause I missed them in the eslint PR.

AriPerkkio

I added theming to tutorial-vite-plugin.pages.dev/ using this guide. The final theme.css is here: https://github.com/AriPerkkio/tutorial-vite-plugin/blob/main/theme.css

Overall the CSS variables work nicely. It felt like I could style most of the stuff I wanted.
Content like <code> and <pre> rendered from markdown were not customizable so I ended up overwriting private APIs:

:root {
  a {
    --link-color: var(--my-color-1);
  }

  pre,
  code {
    --code-background: var(--my-color-2);
    --code-background-color: var(--my-color-3);
    --code-color: var(--my-color-4);
  }
}

Theming editor is not documented here - should it be? I ended up styling it anyway using following vars:
- --tk-elements-editor-backgroundColor
- --tk-elements-editor-gutter-textColor
- --tk-elements-editor-gutter-backgroundColor
HMR works nicely but having Webcontainers restart on every save is a lot. My browser felt really slow at some points.
For some reason --tk-elements-fileTree-file-textColorSelected doesn't work in 0.0.1-alpha.23. It works in TutorialKit's template in main though.

SamVerschueren · 2024-06-26T15:34:19Z

Theming editor is not documented here - should it be?

It should, but I think we need to improve on the editor in general. I would postpone this to a follow-up PR.

For some reason --tk-elements-fileTree-file-textColorSelected doesn't work in 0.0.1-alpha.23. It works in TutorialKit's template in main though.

It could be that I fixed/added this one (can't really remember). If it works on main, I probably did. I found a couple of issues while I was documenting this.

d3lm

Minor comment but LGTM 👍

docs/tutorialkit.dev/src/content/docs/reference/images/theming-editor-gutter-fold.png

docs(theming): add page to describe how to customize tutorialkit

d6c0a59

SamVerschueren requested review from sulco, Nemikolh and d3lm June 25, 2024 13:25

chore: fix links

f8ad1fa

SamVerschueren added 2 commits June 25, 2024 15:57

chore: ignore link validation for guides

debb39b

Merge branch 'main' into docs/theming

ee022bd

chore: small improvements

ded0915

SamVerschueren commented Jun 25, 2024

View reviewed changes

chore: move to theming reference

028e2ac

SamVerschueren changed the title ~~docs(theming): add page to describe how to customize tutorialkit~~ docs(theming): add theming reference to tutorialkit.dev Jun 25, 2024

Merge branch 'main' into docs/theming

095a364

d3lm reviewed Jun 26, 2024

View reviewed changes

d3lm and others added 2 commits June 26, 2024 09:27

Merge branch 'main' into docs/theming

8b4b23b

fix: improve page description.

93d35b2

Co-authored-by: Dominic Elm <[email protected]>

chore: pr feedback

e7b417b

AriPerkkio mentioned this pull request Jun 26, 2024

feat: theme AriPerkkio/tutorial-vite-plugin#4

Merged

SamVerschueren added 3 commits June 26, 2024 10:23

chore: fix some of the descriptions.

47b818e

fix: typo

7c10df9

fix: update images to higher resolution

b628bca

AriPerkkio reviewed Jun 26, 2024

View reviewed changes

SamVerschueren added 3 commits June 26, 2024 11:01

chore: add images for the file tree file and folder

b7e46a8

chore: fix theming title

7fcac03

chore: try astro image component

47e4fc6

chore: increase size of image

0fcec70

Nemikolh approved these changes Jun 26, 2024

View reviewed changes

SamVerschueren and others added 3 commits June 26, 2024 12:34

chore: update images to higher res

398e124

chore: divide width by 3

9397e9a

fixup: update images

5feb62d

d3lm reviewed Jun 26, 2024

View reviewed changes

docs/tutorialkit.dev/src/styles/custom.scss Outdated

Copy link

Contributor

d3lm Jun 26, 2024 •

edited

Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ Updated these cause I missed them in the eslint PR.

Merge branch 'main' into docs/theming

2a93edb

AriPerkkio reviewed Jun 26, 2024

View reviewed changes

SamVerschueren and others added 4 commits June 27, 2024 10:35

chore: document how to theme the editor

bc068b7

docs: add editor images

93442e3

doc: update screenshot

80b862f

Merge branch 'main' into docs/theming

eb24b17

Nemikolh requested a review from d3lm June 27, 2024 10:25

d3lm reviewed Jun 27, 2024

View reviewed changes

docs/tutorialkit.dev/src/content/docs/reference/images/theming-editor-gutter-fold.png Outdated Show resolved Hide resolved

chore: update image

8e75d54

d3lm approved these changes Jun 27, 2024

View reviewed changes

Nemikolh merged commit 0644706 into main Jun 27, 2024
8 checks passed

Nemikolh deleted the docs/theming branch June 27, 2024 14:55

docs(theming): add theming reference to tutorialkit.dev #97

docs(theming): add theming reference to tutorialkit.dev #97

Uh oh!

Conversation

SamVerschueren commented Jun 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bolt-new-by-stackblitz bot commented Jun 25, 2024

Uh oh!

changeset-bot bot commented Jun 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

cloudflare-workers-and-pages bot commented Jun 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying tutorialkit-docs-page with Cloudflare Pages

Uh oh!

cloudflare-workers-and-pages bot commented Jun 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying tutorialkit-demo-page with Cloudflare Pages

Uh oh!

SamVerschueren Jun 25, 2024

Choose a reason for hiding this comment

Uh oh!

sulco commented Jun 25, 2024

Uh oh!

d3lm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SamVerschueren commented Jun 26, 2024

Uh oh!

AriPerkkio left a comment

Choose a reason for hiding this comment

Uh oh!

Nemikolh commented Jun 26, 2024

Uh oh!

Nemikolh left a comment

Choose a reason for hiding this comment

Uh oh!

AriPerkkio commented Jun 26, 2024

Uh oh!

d3lm Jun 26, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AriPerkkio left a comment

Choose a reason for hiding this comment

Uh oh!

SamVerschueren commented Jun 26, 2024

Uh oh!

d3lm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SamVerschueren commented Jun 25, 2024 •

edited

Loading

changeset-bot bot commented Jun 25, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Jun 25, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Jun 25, 2024 •

edited

Loading

d3lm Jun 26, 2024 •

edited

Loading