diff --git a/.gitignore b/.gitignore index 319bab66cafa4..21728725b2f00 100644 --- a/.gitignore +++ b/.gitignore @@ -15,7 +15,7 @@ docs/code docs/_site docs/.sass-cache docs/js/* -docs/downloads +docs/downloads/*.zip docs/vendor/bundle examples/shared/*.js examples/**/bundle.js diff --git a/.travis.yml b/.travis.yml index e2271f6e5d68e..49223f8f34300 100644 --- a/.travis.yml +++ b/.travis.yml @@ -23,7 +23,11 @@ before_install: script: - | if [ "$TEST_TYPE" = build_website ]; then - if [ "$TRAVIS_BRANCH" = "$REACT_WEBSITE_BRANCH" ] && [ "$TRAVIS_PULL_REQUEST" = false ]; then + if [ "$TRAVIS_PULL_REQUEST" = false ]; then + if [ "$TRAVIS_BRANCH" != new-docs ]; then + echo "This code should only run on the new-docs branch. Please revert it." + exit 1 + fi set -e GH_PAGES_DIR="$TRAVIS_BUILD_DIR"/../react-gh-pages @@ -42,7 +46,7 @@ script: if ! git diff-index --quiet HEAD --; then git add -A . git commit -m "Rebuild website" - git push origin gh-pages + git push -f https://reactjs-bot@github.com/reactjs-bot/react.git gh-pages fi popd fi diff --git a/docs/README.md b/docs/README.md index 1b36319b33730..6517ab8bb47da 100644 --- a/docs/README.md +++ b/docs/README.md @@ -38,7 +38,7 @@ $ cd react/docs $ bundle exec rake $ bundle exec rake fetch_remotes $ bundle exec jekyll serve -w -$ open http://localhost:4000/react/ +$ open http://localhost:4000/react/index.html ``` We use [SASS](http://sass-lang.com/) (with [Bourbon](http://bourbon.io/)) for our CSS, and we use JSX to transform some of our JS. diff --git a/docs/_config.yml b/docs/_config.yml index 53fa1d01e8343..d84d29cbd994c 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -20,6 +20,12 @@ defaults: type: pages values: sectionid: blog +- scope: + path: tutorial + type: pages + values: + layout: tutorial + sectionid: tutorial - scope: path: docs type: pages @@ -27,15 +33,16 @@ defaults: layout: docs sectionid: docs - scope: - path: tips + path: contributing type: pages values: sectionid: docs - scope: - path: contributing + path: community type: pages values: - sectionid: docs + layout: community + sectionid: community exclude: - Gemfile - Gemfile.lock diff --git a/docs/_data/nav_community.yml b/docs/_data/nav_community.yml new file mode 100644 index 0000000000000..3740d3af7e89b --- /dev/null +++ b/docs/_data/nav_community.yml @@ -0,0 +1,14 @@ +- title: Community Resources + items: + - id: support + title: Where To Get Support + - id: conferences + title: Conferences + - id: videos + title: Videos + - id: complementary-tools + title: Complementary Tools + href: https://github.com/facebook/react/wiki/Complementary-Tools + - id: examples + title: Examples + href: https://github.com/facebook/react/wiki/Examples diff --git a/docs/_data/nav_docs.yml b/docs/_data/nav_docs.yml index e8f6b69132b35..1be1ce3c07db4 100644 --- a/docs/_data/nav_docs.yml +++ b/docs/_data/nav_docs.yml @@ -1,104 +1,83 @@ - title: Quick Start items: - - id: getting-started - title: Getting Started - - id: tutorial - title: Tutorial - - id: thinking-in-react - title: Thinking in React -- title: Community Resources + - id: installation + title: Installation + - id: hello-world + title: Hello World + - id: introducing-jsx + title: Introducing JSX + - id: rendering-elements + title: Rendering Elements + - id: components-and-props + title: Components and Props + - id: state-and-lifecycle + title: State and Lifecycle + - id: handling-events + title: Handling Events + - id: conditional-rendering + title: Conditional Rendering + - id: lists-and-keys + title: Lists and Keys + - id: forms + title: Forms + - id: lifting-state-up + title: Lifting State Up + - id: composition-vs-inheritance + title: Composition vs Inheritance + - id: thinking-in-react + title: Thinking In React +- title: Advanced Guides items: - - id: conferences - title: Conferences - - id: videos - title: Videos - - id: complementary-tools - title: Complementary Tools - href: https://github.com/facebook/react/wiki/Complementary-Tools - - id: examples - title: Examples - href: https://github.com/facebook/react/wiki/Examples -- title: Guides - items: - - id: why-react - title: Why React? - - id: displaying-data - title: Displaying Data - subitems: - id: jsx-in-depth - title: JSX in Depth - - id: jsx-spread - title: JSX Spread Attributes - - id: jsx-gotchas - title: JSX Gotchas - - id: interactivity-and-dynamic-uis - title: Interactivity and Dynamic UIs - - id: multiple-components - title: Multiple Components - - id: reusable-components - title: Reusable Components - - id: transferring-props - title: Transferring Props - - id: forms - title: Forms - - id: working-with-the-browser - title: Working With the Browser - subitems: - - id: more-about-refs - title: Refs to Components - - id: tooling-integration - title: Tooling Integration - subitems: - - id: language-tooling - title: Language Tooling - - id: package-management - title: Package Management - - id: environments - title: Server-side Environments - - id: addons - title: Add-Ons - subitems: - - id: animation - title: Animation - - id: two-way-binding-helpers - title: Two-Way Binding Helpers - - id: test-utils - title: Test Utilities - - id: clone-with-props - title: Cloning Elements - - id: create-fragment - title: Keyed Fragments - - id: update - title: Immutability Helpers - - id: pure-render-mixin - title: PureRenderMixin - - id: perf - title: Performance Tools - - id: shallow-compare - title: Shallow Compare - - id: advanced-performance - title: Advanced Performance - - id: context - title: Context + title: JSX In Depth + - id: typechecking-with-proptypes + title: Typechecking With PropTypes + - id: refs-and-the-dom + title: Refs and the DOM + - id: optimizing-performance + title: Optimizing Performance + - id: react-without-es6 + title: React Without ES6 + - id: react-without-jsx + title: React Without JSX + - id: reconciliation + title: Reconciliation + - id: context + title: Context + - id: web-components + title: Web Components - title: Reference items: - - id: top-level-api - title: Top-Level API - - id: component-api - title: Component API - - id: component-specs - title: Component Specs and Lifecycle - - id: tags-and-attributes - title: Supported Tags and Attributes - - id: events - title: Event System - - id: dom-differences - title: DOM Differences - - id: special-non-dom-attributes - title: Special Non-DOM Attributes - - id: reconciliation - title: Reconciliation - - id: webcomponents - title: Web Components - - id: glossary - title: React (Virtual) DOM Terminology + - id: react-api + title: React + subitems: + - id: react-component + title: React.Component + - id: react-dom + title: ReactDOM + - id: react-dom-server + title: ReactDOMServer + - id: dom-elements + title: DOM Elements + - id: events + title: SyntheticEvent + - id: addons + title: Add-Ons + subitems: + - id: perf + title: Performance Tools + - id: test-utils + title: Test Utilities + - id: animation + title: Animation + - id: create-fragment + title: Keyed Fragments + - id: update + title: Immutability Helpers + - id: pure-render-mixin + title: PureRenderMixin + - id: shallow-compare + title: Shallow Compare + - id: two-way-binding-helpers + title: Two-way Binding Helpers + diff --git a/docs/_data/nav_tips.yml b/docs/_data/nav_tips.yml deleted file mode 100644 index f568311444bdd..0000000000000 --- a/docs/_data/nav_tips.yml +++ /dev/null @@ -1,38 +0,0 @@ -- title: Tips - items: - - id: introduction - title: Introduction - - id: inline-styles - title: Inline Styles - - id: if-else-in-JSX - title: If-Else in JSX - - id: self-closing-tag - title: Self-Closing Tag - - id: maximum-number-of-jsx-root-nodes - title: Maximum Number of JSX Root Nodes - - id: style-props-value-px - title: Shorthand for Specifying Pixel Values in style props - - id: children-props-type - title: Type of the Children props - - id: controlled-input-null-value - title: Value of null for Controlled Input - - id: componentWillReceiveProps-not-triggered-after-mounting - title: componentWillReceiveProps Not Triggered After Mounting - - id: props-in-getInitialState-as-anti-pattern - title: Props in getInitialState Is an Anti-Pattern - - id: dom-event-listeners - title: DOM Event Listeners in a Component - - id: initial-ajax - title: Load Initial Data via AJAX - - id: false-in-jsx - title: False in JSX - - id: communicate-between-components - title: Communicate Between Components - - id: expose-component-functions - title: Expose Component Functions - - id: children-undefined - title: this.props.children undefined - - id: use-react-with-other-libraries - title: Use React with Other Libraries - - id: dangerously-set-inner-html - title: Dangerously Set innerHTML diff --git a/docs/_data/nav_tutorial.yml b/docs/_data/nav_tutorial.yml new file mode 100644 index 0000000000000..efa090f0cecb1 --- /dev/null +++ b/docs/_data/nav_tutorial.yml @@ -0,0 +1,71 @@ +- title: Tutorial + items: + - id: tutorial + title: Overview + subitems: + - id: what-were-building + title: What We're Building + href: /react/tutorial/tutorial.html#what-were-building + forceInternal: true + - id: what-is-react + title: What is React? + href: /react/tutorial/tutorial.html#what-is-react + forceInternal: true + - id: getting-started + title: Getting Started + href: /react/tutorial/tutorial.html#getting-started + forceInternal: true + - id: passing-data-through-props + title: Passing Data Through Props + href: /react/tutorial/tutorial.html#passing-data-through-props + forceInternal: true + - id: an-interactive-component + title: An Interactive Component + href: /react/tutorial/tutorial.html#an-interactive-component + forceInternal: true + - id: developer-tools + title: Developer Tools + href: /react/tutorial/tutorial.html#developer-tools + forceInternal: true + - id: lifting-state-up + title: Lifting State Up + href: /react/tutorial/tutorial.html#lifting-state-up + forceInternal: true + subitems: + - id: why-immutability-is-important + title: Why Immutability Is Important + href: /react/tutorial/tutorial.html#why-immutability-is-important + forceInternal: true + - id: functional-components + title: Functional Components + href: /react/tutorial/tutorial.html#functional-components + forceInternal: true + - id: taking-turns + title: Taking Turns + href: /react/tutorial/tutorial.html#taking-turns + forceInternal: true + - id: declaring-a-winner + title: Declaring a Winner + href: /react/tutorial/tutorial.html#declaring-a-winner + forceInternal: true + - id: storing-a-history + title: Storing A History + href: /react/tutorial/tutorial.html#storing-a-history + forceInternal: true + subitems: + - id: showing-the-moves + title: Showing the Moves + href: /react/tutorial/tutorial.html#showing-the-moves + forceInternal: true + - id: keys + title: Keys + href: /react/tutorial/tutorial.html#keys + forceInternal: true + - id: implementing-time-travel + title: Implementing Time Travel + href: /react/tutorial/tutorial.html#implementing-time-travel + forceInternal: true + - id: wrapping-up + title: Wrapping Up + href: /react/tutorial/tutorial.html#wrapping-up + forceInternal: true diff --git a/docs/_includes/footer.html b/docs/_includes/footer.html new file mode 100644 index 0000000000000..e2e6fdb65861c --- /dev/null +++ b/docs/_includes/footer.html @@ -0,0 +1,41 @@ + diff --git a/docs/_includes/hero.html b/docs/_includes/hero.html new file mode 100644 index 0000000000000..10530a7060dde --- /dev/null +++ b/docs/_includes/hero.html @@ -0,0 +1,13 @@ +
' | remove: '
' %} +{% else %} +{% assign type = 'website' %} +{% assign sectionTitle = 'React' %} +{% assign description = 'A JavaScript library for building user interfaces' %} +{% endif %} +{% assign title = page.title | append: ' - ' | append: sectionTitle %} -- Ciao, ! - È il {this.props.date.toTimeString()} -
- ); - } -}); - -setInterval(function() { - ReactDOM.render( -- Hello, ! - It is {this.props.date.toTimeString()} -
- ); - } -}); - -setInterval(function() { - ReactDOM.render( -- 안녕, ! - 지금 시간은 {this.props.date.toTimeString()} 입니다. -
- ); - } -}); - -setInterval(function() { - ReactDOM.render( -- Hello, ! - It is {this.props.date.toTimeString()} -
- ); - } -} - -function tick() { - ReactDOM.render( -- Hello, ! - It is {this.props.date.toTimeString()} -
- ); - } -}); - -setInterval(function() { - ReactDOM.render( -- Hello, ! - It is {this.props.date.toTimeString()} -
- ); - } -}); - -setInterval(function() { - ReactDOM.render( -- Hello, ! - It is {this.props.date.toTimeString()} -
- ); - } -}); - -setInterval(function() { - ReactDOM.render( -- You {text} this. Click to toggle. -
- ); - } -}); - -ReactDOM.render( -- You {text} this. Click to toggle. -
- ); - } -}); - -ReactDOM.render( -- You {text} this. Click to toggle. -
- ); - } -}); - -ReactDOM.render( -- You {text} this. Click to toggle. -
- ); - } -}); - -ReactDOM.render( -- You {text} this. Click to toggle. -
- ); - } -}); - -ReactDOM.render( -Paragrafo 1
-Paragrafo 2
-Paragrafo 2
-Paragrafo 1
` è stato rimosso. Invece, React riconcilierà il DOM cambiando il testo contenuto nel primo figlio e distruggerà l'ultimo figlio. React reconcilia secondo l'*ordine* dei figli. - - -### Figli Dotati di Stato - -Per molti componenti, questo non è un grande problema. Tuttavia, per i componenti dotati di stato che mantengono dati in `this.state` attraverso le diverse passate di rendering, questo può essere problematico. - -In molti casi, questo problema può essere aggirato nascondendo gli elementi anziché distruggendoli: - -```html -// Prima passata di rendering -Paragrafo 1
-Paragrafo 2
-Paragrafo 1
-Paragrafo 2
-Paragraph 1
-Paragraph 2
-Paragraph 2
-Paragraph 1
` が削除されたように思えます。代わりに、Reactは1つ目の子要素のテキストコンテンツを変更し、最後の子要素を削除するという変更を加えることでDOMを調和させます。Reactは子要素の *順序* に従って調和するのです。 - - - -### ステートフルな子要素 - -多くのコンポーネントにとって、これは大きな処理ではありません。しかし、レンダリングのパスを超えて、 `this.state` にデータを保持しているステートフルなコンポーネントにとっては、これはとても問題になり得ます。 - -多くのケースにおいては、以下のように、削除する代わりに要素を隠すことで回避することがあります。 - -```html -// パス1のレンダリング -Paragraph 1
-Paragraph 2
-Paragraph 1
-Paragraph 2
-Paragraph 1
-Paragraph 2
-Paragraph 2
-Paragraph 1
`가 없어졌습니다만 그러는 대신에, React는 첫 번째 자식의 텍스트를 비교조정하고 마지막 자식을 파괴하도록 DOM을 비교조정할 것입니다. React는 자식들의 *순서*에 따라 비교조정합니다. - -### 상태기반(Stateful) 자식 - -대부분의 컴포넌트에서는, 이것은 큰 문제가 아닙니다. 하지만 렌더 패스 간에 `this.state`를 유지하는 상태기반의 컴포넌트에서는 매우 문제가 될 수 있습니다. - -대부분의 경우, 이 문제는 엘리먼트를 파괴하지 않고 숨김으로써 피해갈 수 있습니다. - -```html -// Render Pass 1 -Paragraph 1
-Paragraph 2
-Paragraph 1
-Paragraph 2
-Paragraph 1
-Paragraph 2
-Paragraph 2
-Paragraph 1
` was removed. Instead, React will reconcile the DOM by changing the text content of the first child and destroying the last child. React reconciles according to the *order* of the children. - -### Stateful Children - -For most components, this is not a big deal. However, for stateful components that maintain data in `this.state` across render passes, this can be very problematic. - -In most cases, this can be sidestepped by hiding elements instead of destroying them: - -```html -// Render Pass 1 -Paragraph 1
-Paragraph 2
-Paragraph 1
-Paragraph 2
-Paragraph 1
-Paragraph 2
-Paragraph 2
-Paragraph 1
`。事实上,React 先更新第一个子级的内容,然后删除最后一个组件。React 是根据子级的*顺序*来校正的。 - -### 子组件状态管理 - -对于大多数组件,这没什么大碍。但是,对于使用 `this.state` 来在多次渲染过程中里维持数据的状态化组件,这样做潜在很多问题。 - -多数情况下,可以通过隐藏组件而不是删除它们来绕过这些问题。 - -```html -// 第一次渲染 -Paragraph 1
-Paragraph 2
-Paragraph 1
-Paragraph 2
-- React has been running for {this.state.seconds} seconds. -
- ); - } -}); - -ReactDOM.render( -- React has been running for {this.state.seconds} seconds. -
- ); - } -}); - -ReactDOM.render( -- React has been running for {this.state.seconds} seconds. -
- ); - } -}); - -ReactDOM.render( -- React has been running for {this.state.seconds} seconds. -
- ); - } -}); - -ReactDOM.render( -- React has been running for {this.state.seconds} seconds. -
- ); - } -}); - -ReactDOM.render( -