Use aws-amplify/docs as foundation #75

ericclemmons · 2021-07-09T22:35:38Z

See: https://app.asana.com/0/1200334286823427/1200549772234080/f

This is pretty tricky, but I'm attempting to re-use https://github.com/aws-amplify/docs/tree/next for its layout & theme around our content.

https://localhost:5000/ui is the new root, so that URLs are consistent with docs.amplify.aws/ui
- This means the location of features & example pages have moved so that URLs are our contract from docs to features to examples to tests.
Content still goes in src/content/**/index.mdx, but co-locating now works. Use .page.tsx if you need a non-MDX page.
Using xdm instead of @next-js/mdx or next-mdx-* alternatives – they were having issues with getStaticProps and imports.
<Feature name="sign-in"> renders a feature table explicitly within the docs.
There are still more tweaks to be made, but this course-corrects the layout & architecture to avoid the DX issues we've had while aligning with the end-result for launch.

https://pr-75.d3inl0muob87le.amplifyapp.com/ui

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

ericclemmons · 2021-07-12T05:59:09Z

patches/klaw-sync+6.0.0.patch

+-    const st = opts.fs.statSync(pi)
+    const st = opts.fs.lstatSync(pi)


I ran into an issue with amplify-docs, used patch-package, but found it had an issue with symlinks:

manidlou/node-klaw-sync#18

ericclemmons · 2021-07-12T06:09:30Z

docs/package.json

@@ -3,7 +3,7 @@
  "name": "docs",
  "version": "0.0.1",
  "scripts": {
-    "dev": "PORT=5000 next-remote-watch 'src/content' '../packages/e2e/**/*.feature'",
+    "dev": "next dev -p 5000",


No more next-remote-watch because no more next-mdx-remote

ericclemmons · 2021-07-12T06:10:29Z

docs/package.json

    "@xstate/inspect": "^0.4.1",
+    "amplify-docs": "github:https://github.com/aws-amplify/docs#33d383d",


Including https://github.com/aws-amplify/docs as a dependency is buggy with yarn.

The best way I've found was to not use #next, but specify a SHA.

Let me know if you can install & run this locally, or if you run into issues.

I had to do yarn cache clean between version upgrades =/

ericclemmons · 2021-07-12T06:11:00Z

docs/src/components/XStateInspector.tsx


 export function XStateInspector() {
-  return <iframe data-xstate style={{ width: "100%", height: "40ch" }} />;
+  React.useLayoutEffect(() => {
+    inspect();


This seems safer/idiomatic than typeof window checks.

ericclemmons · 2021-07-12T06:11:20Z

docs/src/content/ui/components/authenticator/index.mdx

+import { Authenticator } from "@aws-amplify/ui-react";
+import { XStateInspector } from "@/components/XStateInspector";


@reesscot Explicit imports work now!

ericclemmons · 2021-07-12T06:11:55Z

docs/src/content/ui/primitives/view/index.mdx

@@ -2,6 +2,8 @@
 title: View
 ---

+import { View, ViewDemo } from "@aws-amplify/ui-react"


@reesscot The styles don't seem to be built for this ViewDemo, but that's probably because it's in a separate package still...

I'll cut a PR to move all the demos back to docs

ericclemmons · 2021-07-12T06:13:00Z

docs/src/pages/[[...slugs]].tsx

+  const Content = dynamic(() => import(`../content/${slug}/index.mdx`), {
+    loading() {
+      return <div dangerouslySetInnerHTML={{ __html }} />;
+    },
+  });


This is cool little "progressive enhancement" approach:

dynamically import the component, but statically render the markup.

This way the page renders first & correct with SSG/SSR, but becomes functional onload.

ericclemmons · 2021-07-12T06:14:21Z

docs/src/pages/[[...slugs]].tsx

+  const { default: Content, frontmatter = {} } = await import(
+    `../content/${slug}/index.mdx`


This can potentially impact build times with webpack (because webpack will code-split all matching paths), but since we have a limited number of pages it doesn't seem much different than builds today.

And, honestly, this is working better than fs.readFileSync, next-mdx-remote, and other solutions.

ericclemmons · 2021-07-12T06:15:01Z

docs/src/pages/_app.tsx

+      <script src="https://cdn.jsdelivr.net/npm/docsearch.js@2.6.3/dist/cdn/docsearch.min.js"></script>
+      <script src="https://a0.awsstatic.com/s_code/js/3.0/awshome_s_code.js"></script>
+      <script src="/scripts/shortbreadv1.js"></script>


amplify-docs will throw runtime errors without these scripts 🤷

ericclemmons · 2021-07-12T06:15:11Z

docs/src/styles/styles.css

+}
+
+pre {
+  @apply rounded;


I cut myself on those corners!

…-docs

ericclemmons · 2021-07-12T17:52:25Z

@reesscot I just merged in your changes and I think there's an opportunity to do more colocating of files with demos, like your images:

https://github.com/remcohaszing/remark-mdx-images

ErikCH

This looks good to me other then the conflict and the features not working yet. But I'm guessing the features will be added back to the Authenticator page on a future release?

…-docs

ericclemmons · 2021-07-12T21:48:03Z

docs/src/components/Feature.tsx

@@ -0,0 +1,113 @@
+import {


This is replacing FeatureTests.tsx

ericclemmons · 2021-07-12T21:49:02Z

docs/src/pages/ui/components/authenticator/index.mdx

+## Features
+
+### Sign Up
+
+<Feature name="sign-up" />


Explicitly putting features into the docs now.

This way we have more control of where they appear & how we describe them.

Feature is responsible for showing the Examples table.

swaminator · 2021-07-12T22:28:04Z

Thanks for the work! Know it's still WIP, but couple of questions:

How will we handle platform/framework filtering that exists in today's docs?
If a customer picks 'React' they are able to stay within 'React' throughout the docs site. Will this functionality still work?
How will docs 'search' functionality work with this new site?
When customers hit the 'Edit on GitHub' button in the docs where will they go?
What happens if/when the docs engineering team build out new features? (E.g. a 'Rate this content' feature)
I notice some of the UI components on the page are unique to our content only (e.g. the expander caret here). Is this just a point-in-time thing?

ericclemmons · 2021-07-19T16:04:39Z

The framework chooser is coming. We've just started creating per-platform documentation which will use this (Angular POC clean up #89?)
Mostly – we'll know the framework because the primary docs contain the framework in the url: /q/framework/react. The framework wouldn't be persisted if you started with React & switched to Angular on the UI docs, then went back to the library – that's where putting ?framework=react in the URLs addresses this (vs. relying on React Context).
Search is powered by Algolia's crawler, so it'll pick up the new content during their crawl. I'd honestly prefer a separate search for UI, but that doesn't make sense unless we were a separate "product" page like https://ui.supabase.io/.
If we keep the (terrible) "Edit on GitHub" button have today, it'll go to the page source:
- https://docs.amplify.aws/ui/auth/authenticator/q/framework/react
- https://github.com/aws-amplify/docs/edit/main/docs/ui/auth/authenticator.md
Instead, I want to put the Edit beside the content itself, not the page.
We update the dependency & it's either (1) already part of the layout or (2) we add the component:

https://github.com/aws-amplify/amplify-ui/tree/main/docs#amplify-ui-documentation

I've spoken to @jakeburden about an engineering task to make the docs a Next.js plugin that's source-agnostic – right now, the components are tightly coupled to the docs' filesystem.
Yes, we'll have UI-specific docs & features to accompany them. What I think you're referring to is the HTML <details> element. (Interactive demos, links to tests & features, etc. are other UI-specific features)

ericclemmons added 4 commits July 9, 2021 17:32

Add amplify-docs to use as a dependency

7afe526

Fix issue with patch-package & symlinks in amplify-docs

c513130

"HEAD" => "main"

5b865d1

Reuse amplify-docs' public assets

73d5826

ericclemmons force-pushed the amplify-docs branch from a6f2e1e to a61a475 Compare July 9, 2021 22:48

Use next-mdx-enhanced temporarily with amplify-docs

bd7494c

ericclemmons force-pushed the amplify-docs branch from a61a475 to bd7494c Compare July 9, 2021 22:52

ericclemmons added 7 commits July 10, 2021 15:11

Replace next-mdx-enhanced with @next/mdx

cbc15c9

As a rule, withCompileNodeModules should be _last_

bc2e631

Use shorter hash to match docs/README.md

e9e704e

:whew: This was a PITA to get working, but it's mostly right!

c3d0f1b

Update docs/README.md to match latest conventions

7158581

Ignore TS build errors due to amplify-docs

63840be

Comment on why /ui is redirected

13c7ada

ericclemmons commented Jul 12, 2021

View reviewed changes

ericclemmons added 2 commits July 11, 2021 22:59

Remove need for @/layouts

5bd7899

No need to explicitly set src

a1899fa

ericclemmons requested a review from reesscot July 12, 2021 06:05

ericclemmons self-assigned this Jul 12, 2021

ericclemmons commented Jul 12, 2021

View reviewed changes

ericclemmons marked this pull request as ready for review July 12, 2021 06:17

Fix SecondaryNav matching active by pathname, not asPath

0a587e1

ericclemmons requested a review from a team July 12, 2021 06:22

ericclemmons added 3 commits July 11, 2021 23:51

Merge branch 'main' of github.com:aws-amplify/amplify-ui into amplify…

a828ce3

…-docs

Move all src/content back into src/pages

ff7e2e4

Merge branch 'main' of github.com:aws-amplify/amplify-ui into amplify…

e15adde

…-docs

ErikCH approved these changes Jul 12, 2021

View reviewed changes

ericclemmons added 2 commits July 12, 2021 14:45

Explicitly add features to docs

260bb72

Merge branch 'main' of github.com:aws-amplify/amplify-ui into amplify…

b55cbe4

…-docs

ericclemmons commented Jul 12, 2021

View reviewed changes

docs/src/components/Feature.tsx

@@ -0,0 +1,113 @@

import {

Copy link

Contributor Author

ericclemmons Jul 12, 2021

Choose a reason for hiding this comment

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

This is replacing FeatureTests.tsx

ericclemmons commented Jul 12, 2021

View reviewed changes

Moved example URLs to match docs /ui/*

6493fb7

ErikCH merged commit 64bc331 into main Jul 12, 2021

ErikCH deleted the amplify-docs branch July 12, 2021 22:41

ericclemmons mentioned this pull request Oct 6, 2021

Setup Next.js layout for multi-frameworks #38

Closed

5 tasks

wlee221 mentioned this pull request Jun 8, 2022

chore: resolutions audit and cleanup #2050

Closed

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use aws-amplify/docs as foundation #75

Use aws-amplify/docs as foundation #75

ericclemmons commented Jul 9, 2021 •

edited

ericclemmons Jul 12, 2021

ericclemmons Jul 12, 2021

ericclemmons Jul 12, 2021

ericclemmons Jul 12, 2021

ericclemmons Jul 12, 2021

ericclemmons Jul 12, 2021

reesscot Jul 12, 2021

ericclemmons Jul 12, 2021

ericclemmons Jul 12, 2021

ericclemmons Jul 12, 2021

ericclemmons Jul 12, 2021

ericclemmons commented Jul 12, 2021

ErikCH left a comment

ericclemmons Jul 12, 2021

ericclemmons Jul 12, 2021

swaminator commented Jul 12, 2021 •

edited

ericclemmons commented Jul 19, 2021 •

edited

		- const st = opts.fs.statSync(pi)
		+ const st = opts.fs.lstatSync(pi)

		"@xstate/inspect": "^0.4.1",
		"amplify-docs": "github:https://github.com/aws-amplify/docs#33d383d",

		import { Authenticator } from "@aws-amplify/ui-react";
		import { XStateInspector } from "@/components/XStateInspector";

		const { default: Content, frontmatter = {} } = await import(
		`../content/${slug}/index.mdx`

Use aws-amplify/docs as foundation #75

Use aws-amplify/docs as foundation #75

Conversation

ericclemmons commented Jul 9, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericclemmons commented Jul 12, 2021

ErikCH left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

swaminator commented Jul 12, 2021 • edited

ericclemmons commented Jul 19, 2021 • edited

ericclemmons commented Jul 9, 2021 •

edited

swaminator commented Jul 12, 2021 •

edited

ericclemmons commented Jul 19, 2021 •

edited