Coder Social home page Coder Social logo

facebook / react-native-website Goto Github PK

View Code? Open in Web Editor NEW
1.9K 1.9K 4.3K 187.38 MB

The React Native website and docs

Home Page: https://reactnative.dev

License: MIT License

JavaScript 63.49% CSS 1.10% HTML 1.54% SCSS 28.60% MDX 5.27%
docusaurus react react-native

react-native-website's Introduction

This repo contains the website configuration and documentation powering the React Native website.

If you are looking for the source code of the React Native Archive website select the archive branch.

Contents

✈️ Getting started

Prerequisites

  1. Git.
  2. Node (version 12 or greater).
  3. Yarn (version 1.5 or greater).
  4. A fork of the repo (for any contributions).
  5. A clone of the react-native-website repo.

Installation

  1. cd react-native-website to go into the project root.
  2. Run yarn to install the website's workspace dependencies.

Running locally

  1. cd website to go into the website portion of the project.
  2. yarn start to start the development server (powered by Docusaurus).
  3. Open http://localhost:3000/ site in your favorite browser.

📖 Overview

If you would like to contribute an edit or addition to the docs, read through our style guide before you write anything. Almost all our content is generated from markdown files you can find in the docs, website/architecture and website/contributing directories.

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. 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

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

react-native-website/
├── docs/
│   ├── [BASE VERSIONED DOC FILES]
│   └── ...
└── website/
    ├── architecture/
    │   ├── [ARCHITECTURE DOC FILES]
    │   └── ...
    ├── blog/
    │   ├── [BLOG POSTS]
    │   └── ...
    ├── contributing/
    │   ├── [CONTRIBUTING DOC FILES]
    │   └── ...
    ├── core/
    │   ├── [CUSTOM COMPONENTS]
    │   └── ...
    ├── src/
    │   ├── css/
    │   │   ├── [CUSTOM STYLES]
    │   │   └── ...
    │   ├── pages/
    │   │   ├── [STATIC PAGES]
    │   │   └── ...
    │   └── theme/
    │   │   ├── [SWIZZLED COMPONENTS]
    │   │   └── ...
    ├── static/
    │   ├── blog/
    │   │   └── assets/
    │   ├── docs/
    │   │   └── assets/
    │   └── img/
    ├── versioned_docs/
    │   ├── [GENERATED VERSIONED DOC FILES]
    │   └── ...
    ├── versioned_sidebars/
    │   ├── [GENERATED VERSIONED SIDEBARS]
    │   └── ...
    ├── docusaurus.config.js
    ├── package.json
    ├── showcase.json
    ├── sidebars.json
    ├── sidebarsArchitecture.json
    ├── sidebarsContributing.json
    └── versions.json

Documentation sources

As mentioned above, the docs folder contains the source files for docs from "Guides", "Components" and "APIs" tabs on the React Native website (versioned docs). The doc files for the "Architecture" and "Contribution" tabs are located inside website in the respective directories (unversioned/static docs). In most cases, you will only want to edit the files within those directories.

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, sidebarsArchitecture.json and sidebarsContributing.json files in the website directory. The sidebar files contain a list of document ids that should match those defined in the header metadata (aka frontmatter) of the docs markdown files.

Versioned docs

Part of the React Native website is versioned to allow users to go back and see the Guides or API reference documentation 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.

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 versioned docs.

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

Cutting a new version

After RC

The React Native website lints and typechecks documents in "next". The version of React Native used by the linter should be updated before a release for consistency and to catch any documents/examples where APIs have changed.

This can be done by updating the package.json and configuration files in script/lint-examples the same way a React Native application would be updated. The diff of these files can be seen using a tool like React Native Upgrade Helper.

After Release
  1. cd react-native-website to go into the project root.
  2. cd website to go into the website portion of the project.
  3. Run yarn version:cut <newVersion> where <newVersion> is the new version being released.

🔧 Website configuration

The main config file for the website can be found at website/docusaurus.config.js. This file tells Docusaurus how to build the website. Edits to this file are rarely necessary.

The core subdirectory contains JavaScript and React components that are the core part of the website.

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

The src/theme subdirectory contains the swizzled React components from the Docusaurus theme.

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

👏 Contributing

Create a branch

  1. git checkout main from any folder in your local react-native-website repository.
  2. git pull origin main to ensure you have the latest main code.
  3. git checkout -b the-name-of-my-branch to create a branch.

    replace the-name-of-my-branch with a suitable name, such as update-animations-page

Make the change

  1. Follow the "Running locally" instructions.
  2. Save the files and check in the browser.
  3. Some changes may require a server restart to generate new files. (Pages in docs always do!)
  4. Edits to pages in docs will only be visible in the latest version of the documentation, called "Next", located under the docs/next path.

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

Visit http://localhost:3000/versions to see the list of all versions of the docs.

Test the change

If possible, test any visual changes in all latest versions of the following browsers:

  • Chrome and Firefox on the desktop.
  • Chrome and Safari on mobile.

Push it

  1. Run yarn prettier and yarn language:lint in ./website directory to ensure your changes are consistent with other files in the repo.
  2. 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

  3. git push my-fork-name the-name-of-my-branch
  4. Go to the react-native-website repo and you should see recently pushed branches.
  5. Follow GitHub's instructions.
  6. Describe briefly your changes (in case of visual changes, please include screenshots).

📄 License

React Native is MIT licensed.

React Native documentation is Creative Commons licensed.

react-native-website's People

Contributors

abhinavsagar avatar blakef avatar brentvatne avatar charpeni avatar cortinico avatar cpojer avatar dependabot[bot] avatar ecreeth avatar fortmarek avatar gabrieldonadel avatar gedeagas avatar hramos avatar huntie avatar inokawa avatar kelset avatar lucasbento avatar luism3861 avatar lunaleaps avatar naturalclar avatar nickgerleman avatar rachelnabors avatar rickhanlonii avatar sammy-sc avatar simek avatar slorber avatar sunnylqm avatar tesseralis avatar thesavior avatar vonovak avatar yungsters avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

react-native-website's Issues

how to delete old version form version.json

when i want to delete old version in version.json for 0.5 。 I delete three file, versioned_docs,versioned_sidebars,version.json in 0.5 about. but not work ,may i lost something delete?

Native modules template

Hi,

Trying to build a first RN custom module, the ios guide Is very comprehensive but I was wondering if there is some sort of template repo that I could use to bootstrap my native module, if it doesn't exist I'm happy to start working on it.

Thanks :)

Restore missing style props

In the documentation for the View component the style attribute is pretty much empty.
screen shot 2017-12-06 at 2 32 41 pm

I reported this 7 months ago when it first started happening in version .43-.44 but it was close because the docs were moved to this project.

It would be great if this could get fixed soon, to help out all the people using the versions of react-native that are not fully documented.

Remove out of date reference to ResponderEventPlugin.js

The file ResponderEventPlugin.js is nowhere to be found in the source code of react-native although it is referenced by name 33 times in 6 files. ResponderEventPlugin can be found inside of Libraries\Renderer\ReactNativeRenderer-prod.js though.

Having had a look at ReactNativeRenderer-prod.js I realised that there are neither details nor documentation inside of this file. Thus, I would propose to completely remove this sentence.

#125

How Contribute with Translations for React Native Docs ?

Hello

I would like to translate the React Native Docs in Italian.

I can submit the contributions on Github as I am one of the contributors of Utopian.io

Is there any guide or repository for it?

I look forward to understand how to get started.

Any help appreciated

Thank you

Best Regards
Michael Asumcinei

Algolia DocSearch dropdown is not shown when viewing versioned docs

Is this a bug report?

Yes

Have you read the Contributing Guidelines?

yes

Environment

Environment:
OS: macOS Sierra 10.12.6
Node: 6.11.0
Yarn: 1.3.2
npm: 5.4.2
Watchman: 4.7.0
Xcode: Xcode 8.3.3 Build version 8E3004b
Android Studio: 2.3 AI-162.4069837
Chrome - 63.0.3239.84
Firefox - 57.0

Packages: (wanted => installed)
react-native: 0.48.1 => 0.48.1
react: 16.0.0-alpha.12 => 16.0.0-alpha.12

Target Platform: iOS (10.3)

Steps to Reproduce

(Write your steps here:)

  1. Open Website https://facebook.github.io/react-native/
  2. Search for Switch component using the search bar
  3. Modal drop down appears with appropriate search results
  4. Select Switch component
  5. Inside Switch component docs, search for Button component.
  6. Nothing happens.

But,
7. Go back again to home page i.e https://facebook.github.io/react-native/
8. Search for Button, it shows all search results again.

Expected Behavior

When you search for Button component inside Switch Component docs, a Modal dropdown must appear with all the search results

(Write what you thought would happen.)

Actual Behavior

Nothing happens! the search bar does nothing.

(Write what happened. Add screenshots!)

bug

Reproducible Demo

(Paste the link to an example project and exact instructions to reproduce the issue.)

Timer documentation should mention that timers are paused when backgrounded

https://facebook.github.io/react-native/docs/timers.html

It's common for people to ask something like: "hey I did setInterval(() => /* get location */, 1000) but it doesn't do anything when i background the app, what do i need to do?" -- we should explain that it isn't so simple, and link to the headlessjs doc as well as information about ios and android background execution models. It might even be worth having another section about this that we just link to from timers

The Basics and Guides should not be versioned

We currently allow readers to switch the website version. This lets them see the docs as a snapshot for a given React Native release. For example, what were the APIs for ScrollView back in 0.20 versus 0.50?

Our goal with the content in The Basics and Guides is to provide information that is relevant today, with the assumption that the user is on the latest release.

In order to make this work under our versioning infrastructure*, we've had to place this content in website/versioned_docs/version-0.5, e.g. the oldest public release. By doing so, we're always serving the freshest version of these guides, but we also add some friction as people will need to edit two files (those in docs/ as well as website/versioned_docs/version-0.5) to ensure the edits are not lost when a new release is cut.

We can easily fix this by adding a script that syncs edits made to these specific files. With that in place, we only need to tell our readers to edit the files in docs/ and to ignore anything in website/versioned_docs/.

The list of files that would need to be synced are (as gleaned from sidebars.json):

The Basics

  • docs/getting-started.md
  • docs/tutorial.md
  • docs/props.md
  • docs/state.md
  • docs/style.md
  • docs/height-and-width.md
  • docs/flexbox.md
  • docs/handling-text-input.md
  • docs/handling-touches.md
  • docs/using-a-scrollview.md
  • docs/using-a-listview.md
  • docs/network.md
  • docs/more-resources.md

Guides

  • docs/components-and-apis.md
  • docs/platform-specific-code.md
  • docs/navigation.md
  • docs/images.md
  • docs/animations.md
  • docs/accessibility.md
  • docs/improvingux.md
  • docs/timers.md
  • docs/debugging.md
  • docs/performance.md
  • docs/gesture-responder-system.md
  • docs/javascript-environment.md
  • docs/direct-manipulation.md
  • docs/colors.md
  • docs/integration-with-existing-apps.md
  • docs/running-on-device.md
  • docs/upgrading.md
  • docs/troubleshooting.md

Guides (iOS)

  • docs/native-modules-ios.md
  • docs/native-components-ios.md
  • docs/linking-libraries-ios.md
  • docs/running-on-simulator-ios.md
  • docs/communication-ios.md
  • docs/building-for-apple-tv.md
  • docs/app-extensions.md

Guides (Android)

  • docs/native-modules-android.md
  • docs/native-components-android.md
  • docs/headless-js-android.md
  • docs/signed-apk-android.md
  • docs/android-building-from-source.md

Contributing

  • docs/contributing.md
  • docs/maintainers.md
  • docs/testing.md
  • docs/understanding-cli.md
  • When versioning is enabled, as is the case for this site, the static site generator does not actually serve content from the docs/ folder. Instead, it will go through each sub-directory in website/versioned_docs until it finds the most recent version-* directory that contains the requested document. In this manner, we always serve the most recent version of the doc. Whenever a new version is cut, we check against docs/ and only copy over those files that have changed. This is why these evergreen files listed above are all placed in website/versioned_docs/version-0.5 even though they've all seen multiple edits since version 0.5 - they were manually placed there.

Link needed in blurb about App Transport Security exception

From the Networking page:

By default, iOS will block any request that's not encrypted using SSL. If you need to fetch from a cleartext URL (one that begins with http) you will first need to add an App Transport Security exception. If you know ahead of time what domains you will need access to, it is more secure to add exceptions just for those domains; if the domains are not known until runtime you can disable ATS completely. Note however that from January 2017, Apple's App Store review will require reasonable justification for disabling ATS. See Apple's documentation for more information.

The part about disabling it completely has a link, but how to add an exception for specific domains is not. Linking to a resource that explains how to do this would be useful, particularly for users of create-react-native-app, which seems to hide things like the info.plist file mentioned in this article that appears if you google it.

FlatList Doc

It seems like the FlatList component is recommended in every version of the doc, even though it was only introduced from 0.43.

It would be better to provide a proper ListView docs for the version anterior to 0.43

Proper doc about packaging the apps and deployment

There is a ton of example how to use the react native components but there is no doc how to package the code and deploy it. Mainly there is no doc about
react-native bundle

So please add doc for it or if anybody knows good resource for it then please share it

Improving UX Guide (ongoing)

@frantic wrote in facebook/react-native#14979

As discussed with @brentvatne and other during ChainReact '17, it would be great to have a section in the docs that lists mobile-specific important UX details.

This is a rough checklist:

  • hitSlop
  • tab bar
    • tab selected tab to pop
    • if empty stack, scroll to top
  • touchable with ripple
  • keyboard:
    • autofocus and return key
    • space under keyboard and dismissing
    • keyboard type, capitalization and autocorrect
  • animated with useNativeDriver
    • only some properties supported -- no layout properties. use
      transforms whenever you can rather than width/height/margin,
      so you can take advantage of this
  • nativedriver for animated.event in scroll view or it'll be janky
  • loading states
    • onPressIn trick for preloading
    • placeholder elements
    • using data that you already have to partially render
    • loading state for image: what do you see when it's not there? maybe
      grey placeholder, maybe gradient, maybe activity indicator, maybe
      low-res version
  • deferring rendering expensive (eg: maps) when possible
  • status bar color, size
  • fading in network images
  • cancellable gestures
  • meaningful animations -- shared transitions for example
  • respect battery state
  • prompt before asking permissions
  • portrait / landscape: lock if you don't support
  • android back button: navigation library can do some things but not all
    for you, need to consider where else users expect it to work
  • compress images properly, provide 2x/3x
  • sometimes text should be selectable
  • ellipsize truncated text
  • respect network status
  • splash screen (white flash)
  • maybe don't add an inline submit button to your form (use keyboard submit or add to navbar!)
  • iphonex safe areas

Edit button is linking to versioned_docs instead of docs

I was confused when clicking the Edit button that I was being taken into the versioned_docs/version-X.XX folder.

I'm assuming this is incorrect, based on this quote from README.md:

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.

Sync contribution guide to CONTRIBUTING.md

Prior to the repo split, whenever the website was built, a script would grab the contents of docs/contributing.md and insert them into CONTRIBUTING.md in the root of the facebook/react-native repo.

This allowed us to easily link to nicely-rendered contribution docs on the web while still having an offline, easy to find, copy in the repo itself. GitHub will also highlight any CONTRIBUTING.md file in a repo when a new issue or PR is opened.

This file is not being actively edited, so it's fine to just manually sync them across both repos for now. If someone wants to take a stab at keeping them in sync, feel free to do so.

Warning: You might consider taking a similar approach to how we deploy the website, where we commit directly to the gh-pages branch on the facebook/react-native repo. It's fine to do that for a non-master branch, because those are GitHub-only, but master is just a copy of whatever Facebook stores on the internal repo. We cannot commit directly to master, as doing so (even if we had the necessary permissions) would get the two repos out of sync. This is why we have tooling in place that grabs patches from PRs and applies them internally before syncing them out, instead of allowing regular merges on git.

Can't click on link/button that appears next to each prop title

Each prop title has a link/button to the left of it:

image

This link/button only appears when you hover over the text representing the prop name. Consequently, you cannot click on the link/button because it disappears when you attempt to hover over it in order to click it.

Adam Comella
Microsoft Corp.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.