1# Expo Documentation 2 3This is the public documentation for **Expo**, its SDK, client and services. 4 5You can access this documentation online at https://docs.expo.io/. It's built using next.js on top of the https://github.com/zeit/docs codebase. 6 7> **Contributors:** Please make sure that you edit the docs in the `pages/versions/unversioned` directory if you want your changes to apply to the next SDK version too! 8 9### Running Locally 10 11Download the copy of this repository. 12 13```sh 14git clone https://github.com/expo/expo.git 15``` 16 17Then `cd` into the `docs` directory and install dependencies with: 18 19```sh 20yarn 21``` 22 23Then you can run the app with (make sure you have no server running on port `3000`): 24 25```sh 26yarn run dev 27``` 28 29Now the documentation is running at http://localhost:3000 30 31### Running in production mode 32 33```sh 34yarn run export 35yarn run export-server 36``` 37 38### Editing Docs Content 39 40You can find the source of the documentation inside the `pages/versions` directory. Documentation is mostly written in markdown with the help of some React components (for Snack embeds, etc). The routes and navbar are automatically inferred from the directory structure within `versions`. 41 42### Redirects 43 44#### Server-side redirects 45 46These redirects are limited in their expresiveness - you can map a path to another path, but no regular expressions or anything are supported. See client-side redirects for more of that. Server-side redirects are re-created on each run of `deploy.sh`. 47 48We currently do two client-side redirects, using meta tags with `http-equiv="refresh"`: 49 50- `/` -> `/versions/latest/` 51- `/versions` -> `/versions/latest` 52 53This method is not great for accessibility and should be avoided where possible. 54 55#### Client-side redirects 56 57Use these for more complex rules than one-to-one path-to-path redirect mapping. For example, we use client-side redirects to strip the `.html` extension off, and to identify if the request is for a version of the documentation that we no longer support. 58 59You can add your own client-side redirect rules in `pages/_error.js`. 60 61### Adding Images and Assets 62 63You can add images and assets to the `static` directory. They'll be served by the production and staging servers at `/static`. 64 65### New Components 66 67Always try to use the existing components and features in markdown. Create a new component or use a component from NPM, unless there is no other option. 68 69### Quirks 70 71* You can't have curly brace without quotes: \`{}\` -> `{}` 72* Make sure to leave a empty newline between a table and following content 73 74## A note about versioning 75 76Expo's SDK is versioned so that apps made on old SDKs are still supported 77when new SDKs are relased. The website documents previous SDK versions too. 78 79Version names correspond to directory names under `versions`. 80 81`unversioned` is a special version for the next SDK release. It is not included in production output 82 83`latest` is an untracked folder which duplicates the contents of the folder matching the version number in `package.json`. 84 85Sometimes you want to make an edit in version `X` and have that edit also 86be applied in versions `Y, Z, ...` (say, when you're fixing documentation for an 87API call that existed in old versions too). You can use the 88`./scripts/versionpatch.sh` utility to apply your `git diff` in one version in 89other versions. For example, to update the docs in `unversioned` then apply it 90on `v8.0.0` and `v7.0.0`, you'd do the following after editing the docs in 91`unversioned` such that it shows up in `git diff`: 92 93`./scripts/versionpatch.sh unversioned v8.0.0 v7.0.0` 94 95Any changes in your `git diff` outside the `unversioned` directory are ignored 96so don't worry if you have code changes or such elsewhere. 97 98### Updating latest version of docs 99 100When we release a new SDK, we copy the `unversioned` directory, and rename it to the new version. Latest version of docs is read from `package.json` so make sure to update the `version` key there as well. However, if you update the `version` key there, you need to `rm -rf node_modules/.cache/` before the change is picked up (why? [read this](https://github.com/zeit/next.js/blob/4.0.0/examples/with-universal-configuration/README.md#caveats)). 101 102Make sure to also grab the upgrade instructions from the release notes blog post and put them in `upgrading-expo-sdk-walkthrough.md`. 103 104That's all you need to do. The `versions` directory is listed on server start to find all available versions. The routes and navbar contents are automatically inferred from the directory structure within `versions`. 105 106Because the navbar is automatically generated from the directory structure, the default ordering of the links under each section is alphabetical. However, for many sections, this is not ideal UX. So, if you wish to override the alphabetical ordering, manipulate page titles in `sidebar-navigation-order.js`. 107 108#### Importing from the React Native docs 109 110You can import the React Native docs in an automated way into these docs. 111 1121. Update the react-native-website submodule here 1132. `yarn run import-react-native-docs` 114 115This will write all the relevant RN doc stuff into the unversioned version directory. 116You may need to tweak the script as the source docs change; the script hackily translates between the different forms of markdown that have different quirks. 117 118The React Native docs are actually versioned but we currently read off of master. 119 120TODOs: 121 - Handle image sizing in imports better 122 - Read from the appropriate version (configurable) of the React Native docs, not just master 123 - Make Snack embeds work; these are marked in some of the React Native docs but they are just imported as plain JS code blocks 124