Documentation site #16
Comments
dgp1130
added a commit
that referenced
this issue
Jul 23, 2023
Refs #16. This opens up the `docs/` directory for the public-facing documentation site.
dgp1130
added a commit
that referenced
this issue
Jul 23, 2023
Refs #16. This just sets up a new `@rules_prerender` site which says "Hello, World!".
dgp1130
added a commit
that referenced
this issue
Aug 19, 2023
Also includes a couple assets for the GitHub logo. The dark theme variant is not used yet, but may in the future if we adopt a dark theme. Refs #16.
dgp1130
added a commit
that referenced
this issue
Aug 20, 2023
Refs #16. Forgot to include these in the prior commit.
dgp1130
added a commit
that referenced
this issue
Aug 20, 2023
Refs #16. This was an interesting test case. The panel itself is relatively straightforward, with a hierarchy and expand/collapse behavior. I spent more time than I'd like to admit on the CSS animations trying to get an arrow to rotate, though I did eventually figure it out. The arrow does get noticeably blurry when animated, which is very strange. This behavior applies for Chrome and Firefox. Searching the internet, I found countless hacks which claim to fix this, but none of them worked for me. For the time being, I'm calling this a browser bug. I also tried to animate the reveal of a route's children, however I decided this is not possible as animating to `height: auto;` is generally not feasible today without compromises I wasn't comfotable making. https://css-tricks.com/using-css-transitions-auto-dimensions/ Beyond the CSS, I think `@rules_prerender` did a good job allowing me to shape the structure of how I solved this particular solution. I was able to decouple routes from the `NavPane` component which made for easier testing. HydroActive was also pretty smooth, though it only binds an event listener and not much more. On its own, that was mostly fine. However testing got complicated _fast_. How and what to assert in a `node-html-parser` test is complicated, verbose, and tedious. I can definitely understand the appeal of snapshot testing, even if I don't think that's a good general solution to this problem. Testing the client code is even more complicated due to a separate `test_cases.tsx` file, multiple build targets, and then the WebDriver tests themselves. User code would need to go out of their way to set up WebDriverIO and Jasmine in addition to all this complexity. This could definitely use some streamlining. Also I wonder if there might be a better testing approach with in-browser testing vs WebDriver testing. Could we render `test_cases.tsx` at build time, then instrument a test runner which serves them with Jasmine loaded in. If it auto-deferred the root component and ran test code inside the browse, we could take advantage of HydroActive test APIs. Need to think more about how viable this is and where tests would be most useful.
dgp1130
added a commit
that referenced
this issue
Sep 8, 2023
Refs #16. This constructs a `SafeHtml` object from a string literal constant. Since it is a tagged template literal, it is guaranteed to be a constant authored by a developer not dependent on user input and therefore "safe" for usage.
dgp1130
added a commit
that referenced
this issue
Sep 8, 2023
Refs #16. This got a little involved, but I learned a lot in the process here. The general pipeline is: 1. Perform an `async` read of the `getting_started.md` file. 2. Parse the markdown with `gray-matter` to separate the frontmatter and markdown body. 3. Parse the markdown body with `marked` and transform it into HTML. 4. Validate the frontmatter with a `zod` schema. 5. Render the page in Preact. This relies on a "fetch-then-render" approach, where all the data is loaded up front asynchronously _and then_ rendered afterwards. I initially tried a "fetch-as-you-render" approach with `<Suspense />` but found it to be a bit lacking. Preact's `<Suspense />` implementation is still experimental, and currently intended for lazy loading components. Data loading with `<Suspense />` is not really a well-trodden path and does not have defined primitives, either in Preact or React. Most React frameworks seem to define their own data loading primitives which I was initially hoping to avoid, letting users structure their own rendering process. For now, the easiest option is to fetch data up front and render afterwards. This isn't great performance and I'm not totally satisfied with it, but it's good enough for now. In the future, hopefully we can revisit async Preact and come away with a better path forward. [See discussion in `preact-ssr-prepass`.](preactjs/preact-ssr-prepass#55)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Currently, all the user-facing documentation is in the root README of the repo. This is good enough for v0 release, but I'd like something more comprehensive for v1.
Ideally, we would have a separate site for documentation about
rules_prerender, as I would prefer if README's and docs in the GitHub repo were internal documentation only, not intended to be user facing. The separate documentation site should provide everything users need to know and any information explicitly covered in the API contract.This also serves as a good test case for
rules_prerender, as documentation sites generally work well with a static site generator model, as they don't change frequently and don't rely on prerendering user data. This can act as a real-world use case ofrules_prerender.The text was updated successfully, but these errors were encountered: