Henry Wilkinson 0a1f5eff8e

Docs: adds mkdocs features, adds theming (#728 )

* Add stylesheet & mkdocs features

- Adds a custom stylesheet & brand colours
- Adds Recursive as the code font
- Adds repo info to the nav bar
- Adds auto tracking ID links for deep linking to sections as users scroll the page
- Index pages are now a part of their section as determined by their H1
- Removes mkdocs info from future footer

* Reorganize content

- Renames "Dev" to "Develop" for improved navigation labels
- Adds links to tools the first time they're mentioned
- Rewords part of the homepage
- Hides section navigation on the homepage (now we don't have a blank section nav bar!
- Adds some syntax highlighting
- Removes some manual word wrapping — this was done very rarely / inconsistently

* Rename "Developer Docs" index page

- Better title for sidebar

* Update docs.md

- Adds links to tools
- Adds future docs style guide section
- Updates name and makes it an H1

- Replaces hyphens on the homepage with em dashes

* deployment index page: changed title, removed non-k8s section, cleaned up intro
* develop index page: changed title
fixed typo on main page

---------

Co-authored-by: Ilya Kreymer <ikreymer@gmail.com>

2023-04-06 02:44:19 -07:00

3.0 KiB

Raw Blame History

Running the Frontend

This guide explains how to deploy an instance of the Browsertrix Cloud frontend for development. The frontend can connect to a Browsertrix Cloud API backend running locally or remotely.

Quickstart

Ensure the current working directory is set to the /frontend folder.

Install dependencies:

yarn

Copy environment variables from the sample file:

cp sample.env.local .env.local

Update API_BASE_URL in .env.local to point to your dev backend API. For example:

API_BASE_URL=http://dev.example.com/api

If connecting to a local deployment cluster, set API_BASE_URL to:

API_BASE_URL=http://localhost:30870/api

Start the dev server:

yarn start

This will open localhost:9870 in a new tab in your default browser.

To develop against a local instance of the backend API, follow instructions for deploying to a local Docker instance. Update API_BASE_URL and then restart the dev server.

Scripts

`yarn <name>`
`start`	runs app in development server, reloading on file changes
`test`	runs tests in chromium with playwright
`build-dev`	bundles app and outputs it in `dist` directory
`build`	bundles app, optimized for production, and outputs it to `dist`
`lint`	find and fix auto-fixable javascript errors
`format`	formats js, html and css files
`localize:extract`	generate XLIFF file to be translated
`localize:build`	output a localized version of strings/templates

Testing

Tests assertions are written in Chai.

To watch for file changes while running tests:

yarn test --watch

To run tests in multiple browsers:

yarn test --browsers chromium firefox webkit

Localization

Wrap text or templates in the msg helper to make them localizable:

// import from @lit/localize:
import { msg } from "@lit/localize";

// later, in the render function:
render() {
  return html`
    <button>
      ${msg("Click me")}
    </button>
  `
}

Entire templates can be wrapped as well:

render() {
  return msg(html`
    <p>Click the button</p>
    <button>Click me</button>
  `)
}

See: https://lit.dev/docs/localization/overview/#message-types

To add new languages:

Add BCP 47 language tag to targetLocales in lit-localize.json
Run yarn localize:extract to generate new .xlf file in /xliff
Provide .xlf file to translation team
Replace .xlf file once translated
Run yarn localize:build bring translation into src

See: https://lit.dev/docs/localization/overview/#extracting-messages

3.0 KiB Raw Blame History