Skip to content

update Readme file, add TOC, add badge #1769

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nearestnabors merged 6 commits into from
Mar 20, 2020
Merged

update Readme file, add TOC, add badge #1769

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
75077be
update Readme file
Simek Mar 18, 2020
906e09b
correct internal links
Simek Mar 18, 2020
58dacde
fix license link
Simek Mar 18, 2020
fe9f960
use code formatting for the paths
Simek Mar 18, 2020
fbb5669
add 'package.json' to the directory structure diagram
Simek Mar 18, 2020
6389ff5
formatting, links, text tweaks
Simek Mar 20, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 48 additions & 34 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,35 +1,43 @@
# [reactnative.dev](https://reactnative.dev/) · [![Circle CI Status](https://circleci.com/gh/facebook/react-native-website.svg?style=shield)](https://circleci.com/gh/facebook/react-native-website) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
# [reactnative.dev](https://reactnative.dev/) · [![CC BY 4.0 license](https://img.shields.io/badge/license-CC%20BY%204.0-blue.svg)](LICENSE-docs) [![Circle CI Status](https://circleci.com/gh/facebook/react-native-website.svg?style=shield)](https://circleci.com/gh/facebook/react-native-website) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

This repo contains the website configuration and documentation powering the [React Native website](https://reactnative.dev/).

## Getting started
## Contents

- [Getting started](#-getting-started)
- [Overview](#-overview)
- [Website configuration](#-website-configuration)
- [Contributing](#-contributing)
- [License](#-license)

## ✈️ Getting started

### Prerequisites

1. Git
1. Node: install version 8 or greater.
1. Yarn: See [Yarn website for installation instructions](https://yarnpkg.com/lang/en/docs/install/). (needs 1.5 or greater).
1. A fork of the repo (for any contributions).
1. [Git](https://git-scm.com/downloads).
1. [Node](https://nodejs.org/en/download/) _(version 10 or greater)_.
1. [Yarn](https://yarnpkg.com/lang/en/docs/install/) _(version 1.5 or greater)_.
1. A fork of the repo _(for any contributions)_.
1. A clone of the `react-native-website` repo.

### Installation

1. `cd react-native-website` to go into the project root.
1. `cd website` to go into the website portion of the project.
1. `yarn` to install the website's npm dependencies (or `npm install`, if not using Yarn).
1. `yarn` or `npm install` to install the website's npm dependencies.

### Running locally

1. `yarn start` to start the development server (powered by Docusaurus) (or `npm start`, if not using Yarn).
1. `yarn start` or `npm start` to start the development server _(powered by [Docusaurus](https://docusaurus.io))_.
1. `open http://localhost:3000/` to open the site in your favorite browser.

# Overview
## 📖 Overview

If you would like to _contribute an edit or addition to the docs,_ read through our [style guide](STYLEGUIDE.md) before you write anything. All our content is generated from markdown files you can find in the 'docs/' directory.
If you would like to **_contribute an edit or addition to the docs,_** read through our [style guide](STYLEGUIDE.md) before you write anything. All our content is generated from markdown files you can find in the `docs` directory.

_To edit the internals of how the site is built,_ you may want to get familiarized with how the site is built. The React Native website is a static site generated using [Docusaurus](https://docusaurus.io). The website configuration can be found in the 'website/' directory. Visit the Docusaurus website to learn more about all the available configuration options.
**_To edit the internals of how the site is built,_** you may want to get familiarized with how the site is built. The React Native website is a static site generated using [Docusaurus](https://docusaurus.io). The website configuration can be found in the `website` directory. Visit the Docusaurus website to learn more about all the available configuration options.

## Directory Structure
### Directory Structure

The following is a high-level overview of relevant files and folders.

Expand All @@ -47,7 +55,6 @@ react-native-website/
├── core/
├── pages/
│ └── en/
│ ├── ...
│ ├── index.js
│ └── ...
├── static/
Expand All @@ -60,39 +67,42 @@ react-native-website/
├── versioned_sidebars/
│ ├── version-0.5-sidebars.json
│ └── ...
├── package.json
├── showcase.json
├── sidebars.json
├── siteConfig.js
└── versions.json
```

## Documentation sources
### Documentation sources

As mentioned above, the 'docs/' folder contains the source files for all of the docs in the React Native website. In most cases, you will want to edit the files within this directory. If you're adding a new doc or you need to alter the order the docs appear in the sidebar, take a look at the 'sidebars.json' file in the 'website/' directory. The sidebars file contains a list of document ids that should match those defined in the header metadata (aka frontmatter) of the docs markdown files.
As mentioned above, the `docs` folder contains the source files for all of the docs in the React Native website. In most cases, you will want to edit the files within this directory. If you're adding a new doc or you need to alter the order the docs appear in the sidebar, take a look at the `sidebars.json` file in the `website` directory. The sidebars file contains a list of document ids that should match those defined in the header metadata (aka frontmatter) of the docs markdown files.

### Versioned docs

The React Native website is versioned as to allow users to go back and see the API reference docs for any given release. A new version of the website is generally made whenever there is a new React Native release. When this happens, any changes made to the 'docs/' and 'website/sidebars.json' files will be copied over to the corresponding location within 'website/versioned_docs/' and 'website/versioned_sidebars/'.
The React Native website is versioned as to allow users to go back and see the API reference docs for any given release. A new version of the website is generally generated whenever there is a new React Native release. When this happens, any changes made to the `docs` and `website/sidebars.json` files will be copied over to the corresponding location within `website/versioned_docs` and `website/versioned_sidebars`.

> Do not edit the auto-generated files within 'versioned_docs/' or 'versioned_sidebars/' unless you are sure it is necessary. Edits made to older versions will not be propagated to newer versions of the docs.
> **_Note:_** Do not edit the auto-generated files within `versioned_docs` or `versioned_sidebars` unless you are sure it is necessary. Edits made to older versions will not be propagated to newer versions of the docs.

Docusaurus keeps track of the list of versions for the site in the 'website/versions.json' file. The ordering of the versions in this file should be in reverse chronological order.
Docusaurus keeps track of the list of versions for the site in the `website/versions.json` file. The ordering of the versions in this file should be in reverse chronological order.

#### Cutting a new version

1. `cd react-native-website` to go into the project root.
1. `cd website` to go into the website portion of the project.
1. Run `yarn run version <newVersion>` where `<newVersion>` is the new version being released.
1. Run `yarn run version <newVersion>` or `npm run version <newVersion>` where `<newVersion>` is the new version being released.

## 🔧 Website configuration

## Website configuration
The main config file for the website can be found at `website/siteConfig.js`. This file tells [Docusaurus how to build the website](http://docusaurus.io/docs/en/site-config.html). Edits to this file are rarely necessary.

The main config file for the website can be found at 'website/siteConfig.js'. This file tells [Docusaurus how to build the website](http://docusaurus.io/docs/en/site-config.html). Edits to this file are rarely necessary.
The `core` subdirectory contains JavaScript and React components that are the core part of the website, such as the SnackPlayer.

The 'pages/' subdirectory contains the React components that make up the non-documentation pages of the site, such as the homepage.
The `pages` subdirectory contains the React components that make up the non-documentation pages of the site, such as the homepage.

The 'showcase.json' file contains the list of users that are highlighted in the React Native showcase.
The `showcase.json` file contains the list of users that are highlighted in the React Native showcase.

## Contributing
## 👏 Contributing

### Create a branch

Expand All @@ -102,29 +112,33 @@ The 'showcase.json' file contains the list of users that are highlighted in the

### Make the change

1. Follow the "Running locally" instructions.
1. Follow the "[Running locally](#running-locally)" instructions.
1. Save the files and check in the browser.
1. Some changes may require a server restart to generate new files. (Pages in **/docs** always do!)
1. Edits to pages in **/docs** will only be visible in the latest version of the documentation, called "Next," under **/docs/next**. Visit **http://localhost:3000/docs/next/YOUR-DOCS-PAGE** to see your work.
1. Some changes may require a server restart to generate new files. (Pages in `docs` always do!)
1. Edits to pages in `docs` will only be visible in the latest version of the documentation, called "Next", under `docs/next`.

Visit **http://localhost:3000/docs/next/YOUR-DOCS-PAGE** to see your work.

> `open http://localhost:3000/versions.html` to see older versions of the docs.

### Test the change

If possible, test any visual changes in all latest versions of Firefox and Chrome on desktop and Safari and Chrome on mobile.
If possible, test any visual changes in all latest versions of the following browsers:

- Chrome and Firefox on desktop.
- Chrome and Safari on mobile.

### Push it

1. Run `yarn prettier` to ensure your changes are consistent with other files in the repo.
1. `git add -A && git commit -m "My message"` (replacing `My message` with a commit message, such as `Fixed header logo on Android`) to stage and commit your changes.
1. Run `yarn prettier` or `npm run prettier` to ensure your changes are consistent with other files in the repo.
1. `git add -A && git commit -m "My message"` to stage and commit your changes.
> replace `My message` with a commit message, such as `Fixed header logo on Android`
1. `git push my-fork-name the-name-of-my-branch`
1. Go to the [react-native-website repo](https://github.com/facebook/react-native-website) and you should see recently pushed branches.
1. Follow GitHub's instructions.
1. If possible, include screenshots of visual changes.

---
1. Describe briefly your changes (in case of visual changes, please include screenshots).

## License
## 📄 License

React Native is [MIT licensed](./LICENSE).

Expand Down