Skip to content

Commit

Permalink
Improve docs (translation tool, URL rewriting #355)
Browse files Browse the repository at this point in the history
  • Loading branch information
m-mohr committed Aug 17, 2023
1 parent 659873b commit d4bb045
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 4 deletions.
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,8 +68,11 @@ npm run build -- --catalogUrl="https://earth-search.aws.element84.com/v1/"
This will only work on the root path of your domain though. If you'd like to publish in a sub-folder,
you can use the [`pathPrefix`](docs/options.md#pathprefix) option.

After building, `dist/` will contain all assets necessary to
After building, `dist/` will contain all assets necessary
host the browser. These can be manually copied to your web host of choice.
**Important:** If `historyMode` is set to `history` (which is the default value), you'll need to add
an additional configuration file for URL rewriting.
Please see the [`historyMode`](docs/options.md#historymode) option for details.

You can customize STAC Browser, too. See the options and theming details below.
If not stated otherwise, all options can either be specified via CLI, ENV variables or in the [config file](config.js).
Expand Down Expand Up @@ -113,6 +116,8 @@ The following languages are currently supported:
- it: Italian (Italy, Switzerland)
- ro: Romanian

We manage the translations in Crowdin, please see <https://crowdin.com/project/stac-browser/> for details.

To add your own language, please follow the guide below: [Adding a new langauge](#adding-a-new-language)

#### Custom phrases
Expand Down Expand Up @@ -282,6 +287,7 @@ You can also use one of the existing languages and provide an alternate version
- Adapt the `datepicker.js` and `duration.js` files to import the existing definitions from their corresponding external packages, but you could also define the specifics yourself.
- Check that your translation works by running the development server (`npm start`) and navigating to the STAC Browser instance in your browser (usually `http://localhost:8080`).
- Once completed, please open a pull request and we'll get back to you as soon as possible.
- After merging the PR for the first time, we'll add you to our translation management tool Crowdin: <https://crowdin.com/project/stac-browser/>. Please get in touch to get your invite!

# Sponsors

Expand Down
21 changes: 18 additions & 3 deletions docs/options.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,9 +129,24 @@ Validation is automatically disabled in the following cases:

***build-only option***

STAC Browser defaults to using [HTML5 History Mode](https://v3.router.vuejs.org/guide/essentials/history-mode.html#html5-history-mode),
which can cause problems on certain web hosts. To use _hash mode_, set `--historyMode=hash` when running or building.
This will be compatible with S3, stock Apache, etc.
### `history`
STAC Browser defaults to _history mode_ (value `history` in the config file), which is based on
[HTML5 History Mode](https://v3.router.vuejs.org/guide/essentials/history-mode.html#html5-history-mode).
It gives the best experience and allows search engines to better crawl STAC Browser so that it can be found in search engines.

**History mode requires that you enable custom URL rewriting rules on your host/server**, otherwise people can not reload pages
or share URLs without getting a "page not found" error (404).
The following link explains the details and provides examples for various common server software:
**<https://v3.router.vuejs.org/guide/essentials/history-mode.html#example-server-configurations>**

Please note that you can't host any other files in the folder that STAC Browser is in as the URL rewriting
will redirect all requests to these (sub)-folders and included files to STAC Browser.
This also excludes hosting your STAC catalog in the STAC Browser (sub-)folders.

### `hash`
If your host/server doesn't support URL rewriting or you experience other related problems, you can enable _hash mode_.
Either set this option to `hash` in the config file or append `--historyMode=hash` when running or building.
Known hosts that require hash mode are Amazon S3 and GitHub Pages.

## pathPrefix

Expand Down

0 comments on commit d4bb045

Please sign in to comment.