Skip to content

Latest commit

 

History

History
114 lines (76 loc) · 4.08 KB

README.md

File metadata and controls

114 lines (76 loc) · 4.08 KB
Raw

Amplify UI Documentation

These docs are published at https://docs.amplify.aws/ui and powered by the following technologies:

Contributing

Getting Started

  1. Navigate to the root of your local clone of aws-amplify/amplify-ui
  2. Run yarn setup
  3. Run yarn docs dev
  4. Open http://localhost:5000/
  5. Optional: To build the flutter authenticator sample, install flutter and then run yarn flutter:build. This will build the flutter authenticator one time. It will not watch for changes.

Note: to set up local environment

cp ./docs/.env.example ./docs/.env

Then set values to the variables in the ./docs/.env file. The values don't matter for local testing. They only matter if you are actually trying to make the Search work.

Note, if you're not using nvm, you'll need to set the environment variable: export NODE_OPTIONS=--openssl-legacy-provider

Test

From the monorepo root run:

$ yarn docs test

Updating Props Table Snapshot

To update the Props Table snapshot run:

$ yarn docs test -u __tests__/props-table.test.ts

Creating a Page

Page paths mirror their URLs. For example, /react/connected-components/authenticator is located at docs/src/pages/[platform]/connected-components/authenticator/index.page.mdx.

Primitive component pages are located at src/pages/[platform]/components/*/index.page.mdx, respectively.

At a minimum, all .page.mdx files require the following basic frontmatter:

---
title: Alert
description: Alert displays a brief message in a way that attracts the user’s attention without interrupting their task.
supportedFrameworks: react
---

Content goes here...

My Title will show up in the sidebar navigation, while content will be statically generated & indexed.

Note that dynamic content (e.g. import Page from "${slug}.mdx") is not statically generated and harder to index. Because of this, ensure indexable content always exists and only supplemental content & demos are loaded asynchronously.

Pages must end with .page.(mdx|tsx) to differentiate them supplemental .mdx fragments or .tsx utilities.

Meta Information

As default, pages use its title and description information as meta information. If you would like to override it with different message, you can use metaTitle or metaDescription.

Host on Amplify

To preview the changes you made for this Amplify UI Docs, you can use Amplify to host your feature branch for the forked repository by following these steps.

Then you need to:

  1. After selecting a branch, check "Connecting a monorepo? Pick a folder." and at "Enter the root directory of your app (e.g. src/myapp)", enter "docs"
  2. Set "Environment variables" from the left sidebar. Add "SITE_URL", "DOCSEARCH_DOCS_APP_ID", "DOCSEARCH_DOCS_API_KEY", "DOCSEARCH_DOCS_INDEX_NAME".
    • "SITE_URL": feel free to use any string
    • "DOCSEARCH_DOCS_APP_ID", "DOCSEARCH_DOCS_API_KEY", "DOCSEARCH_DOCS_INDEX_NAME". If you have them from Algolia DocSearch, use them. Otherwise, please use DocSearch's testing credentials
    • "NODE_OPTIONS": may not be necessary but will help resolve GC/memory errors when deploying 
      DOCSEARCH_DOCS_APP_ID="R2IYF7ETH7"
DOCSEARCH_DOCS_API_KEY="599cec31baffa4868cae4e79f180729b"
DOCSEARCH_DOCS_INDEX_NAME="docsearch"
SITE_URL="https://localhost:5001" # can be any string
NODE_OPTIONS="--max_old_space_size=32768"

Link Checking Locally

Run the following commands from the monorepo entry point

  1. Build the docs site:
$ yarn docs build
  1. Run the build:
$ yarn docs start
  1. In a separate terminal window, run link checking:
$ yarn docs test:links