Site update has a ton of new documentation, and Docusaurus v3.8 plus small improvements

Various Announcements
1

I have merged #348 which a ton of new documenation:

  • FreeSewing.dev:
    • Documentation for all components in @freesewing/react
    • Documentation for all context in @freesewing/react
    • Documentation for all hooks in @freesewing/react
  • FreeSewing.eu:
    • Wrote new documentation for the pattern editor, removed (some) old documentation

In doing this, I also made some changes and improvements to the editor, and there’s some things that are changed are different in a way that is relevant for contributors. Check the PR for remarks, but rest assured that I have already migrated everything.

This also includes the upgrade to docusaurus 3.8.

That being said, there’s two things to keep in mind:

  • If something suddenly breaks, please let me know
  • Sorry for not looking after the open pull requests recently, I really wanted to try and finish this this weekend as it’s been 3 weeks in the making and I was really really really bored of spending all my time writing documentation.
1 Like
2

Welp :see_no_evil_monkey: I had to roll back the production deploy because there’s a new bag of CSS issues that is causing unexpected issues. You can see for yourself here: https://683c755651d08050b5d68bce--freesewing-org.netlify.app/

I suspect this is caused by the CSS Cascade Layers feature that is new in Docusaurus 3.8 and which I enabled because I hoped it would fix some of the lingering CSS issues.

Instead it seems to have made (some) things worse, so I’ll need to look into it deeper. But I’ve run all out of steam for now, so you’ll need to bear with me.

That being said, it’s merged in the develop branch, so if you’d like to take a stab at fixing it yourself, don’t let me stop you :wink:

1 Like
3

Did #348 cause previous commits to be reverted in develop?

For example, I no longer see commit af0dcc9784 applied to sites/dev/docs/tutorials/pattern-design/part2/drawing-the-straps/readme.mdx.

And, I don’t see af0dcc9784’s changes in all the other pattern tutorial files.

Other examples:
d6a1ea81db missing from sites/dev/docs/reference/api/path/intersectsbeam/readme.mdx

d6a1ea81db is present in sites/dev/docs/reference/macros/sa/readme.mdx’s history, but the changes are missing in current develop

e365939432 is present in sites/dev/docs/reference/api/point/flipy/readme.mdx’s history, but the changes are missing in current develop.

Looking closer at sites/dev/docs/reference/api/point/flipy/readme.mdx, I see that the revert seems to have occurred in b914b6299f, but the changes don’t appear in git log --patch. Instead, I have to do a manual git diff e36593943292ba48b0c71acb255632358e100ace b914b6299f53c56250cc954a4869c26be9afe393 sites/dev/docs/reference/api/point/flipy/readme.mdx to see the changes.

4

It was a clean merge, there were no conflicts, so if something went missing it was certainly not intended.

We’ll have to look into it, thanks for pointing it out.

5

I filed PR #430 to redo the fixes that were accidentally reverted.

6

The only CSS problem that I was able to see is that the navbar logo is extremely large.

From experimenting with npm run org, I see that the problem is no longer seen with:

--- a/sites/org/src/css/custom.css
+++ b/sites/org/src/css/custom.css
+.navbar__logo img {
+  height: 100%;
+}
+

I don’t understand how the CSS infrastructure of FreeSewing, Tailwind, React, and Docusaurus are set up or how they are supposed to interact, but the problem seems to be that, with CSS Cascade Layers enabled, the @layer docusaurus.infima {height: 100%;} gets superseded by @layer base {height: auto;}.

I filed PR #435 with the above code change, in case it is an appropriate fix.

7

The CSS problem seem to be caused by Docusaurus styles loading before Tailwind styles, which gives tailwind layers priority oder Docusaurus layers. This causes tailwind defaults (like making images full-size by default) to override specific docusaurus styles like the logo positioning.

A better fix may be to load tailwind before docusaurus, but I couldn’t find an easy way to do so. The custom.css with the default styles seems to be always loaded after the internal docusaurus theme.

Things that are broken apart from the logo are the styles in the navbar, it is now much more compact than before.

8

Work is making it nigh impossible to spend meaningful time on this during the week, but, I will sort it out during the weekend.

My hope is that a few fixes left and right to that are easy to debug will replace the ongoing colour/themeing issues that are much harder to reproduce :crossed_fingers:

1 Like
9

I spent a lot of time today trying to change the priority of the layers in docusaurus (what @jonathan_haas wrote above perfectly captures the crux of the problem), but no matter what I tried, it ended up not working, not to mention making a bunch of other stuff worse in the process.

So I’ve disabled the cascading layers for now, guess we’ll deal with that when docusaurus 4 comes around.

I have deployed a preview version of both websites, based on the current develop branch.
If it looks ok, then I’d like to promoted these to production since there’s a lot of fixes and improvements in the develop branch that I’m certain our users would like to benefit from.

So if you’ve got some time to spare, why not click around a bit on these two sites:

10

I’ve been using the 2 preview sites a bit since yesterday, and they seem to work just fine. (But, I’m specifically ignoring all CSS light/dark issues for now.)

I didn’t see any new bugs, but the previously-seen bugs (like Layout View page crashes) are also still there.

I looked a bit at the .eu site Editor documentation because the Table of Contents looked a bit weird with how the “aka xxxxx view” text was formatted, but eventually decided it was probably fine the way it is.

Print Settings Menu will need to replace Layout Menu in the Editors Menu section on the Editor docs page, and the Print Settings Menu doc wll need to be added. Some additional info will need to be added to the various views docs (like the Apply Layout button in Layout view).

11

Thanks. Earlier today, I deployed the production site with everything in those previews, plus some extra style/CSS fixes that resolved all the styling issues that I could reproduce recently.

As I write this, I am unable to get either freesewing.eu or freesewing.dev to misbehave with regards to the light/dark mode issues.