Improve readme.md
#1256
Improve readme.md
#1256
Conversation
* t.o.c. to be introduced again
+ move section up one level
Adds missing links
|
Found another missing docs ticket: #630 (comment) if you could add this that would be amazing ❤️ |
|
Well if you want to add more docs there's also #1229 😄 but personally I'd consider the PR already good enough, then refine things in a new one. |
|
Thanks guys for having a read through. @timneutkens I'm guessing you are especially looking at As for more missing docs: I'm with @sedubois and would rather get this PR approved and merged as is. And make changes in following PRs. |
|
I also think that the README is starting to show its limits. Ideally Next.js needs a proper documentation website... Then starting from there, it could later also have a nice gallery of examples, with screenshots and a link to each of their versions deployed on Now. |
|
@rauchg mentioned here that he'd like to stick with the readme. I don't mind either way. Personally I like Gitbook. But these options always come with added maintenance overhead—keeping code and docs in one place is always nice. Plus @timneutkens I'll look into how we might automate numbered sections, as |
readme.md
Outdated
|
This is great @nikvm, thanks! If I could add one further request: this PR improves the warning somewhat about |
|
@bdefore How should we make it more obvious? Add more @timneutkens I thought a little more about numbered sections. The problem I see is when adding sections not to the end of a level. This might break links referencing a particular section. As headings get auto-linked it's also not trivial to exclude the numbering. So I still hesitate implementing numbering. |
|
@timneutkens how about merging this? It's going to get more and more conflicts otherwise |
readme.md
Outdated
| #### Imperatively | ||
| - `pathname: string` – Current path excluding the query string | ||
| - `query: Object` – Parsed query string. Defaults to `{}`. | ||
| - `push(url: string, as?: string): boolean` – Performs a [`pushState`](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Example_of_pushState()_method) call with the given url. Returns `true` on success, else `false`. |
There was a problem hiding this comment.
we've deprecated push and replace, we want people to use Router.push and Router.replace
readme.md
Outdated
|
|
||
| Install it: | ||
| First up, install Next.js and it's peer dependencies via [npm](https://npmjs.com/package/next): |
|
@nikvm please merge https://github.com/nikvm/next.js/pull/2 then I can merge this in. Thanks! 🤗 |
|
@nikvm sorry i'm so late to respond, but at this point it's not important to highlight the difference between master and stable release. looking forward to the major bump! |
|
@bdefore we will remove it right before 2.0 is released. |
* Add better hash URL support. (#1250) * Add better hash URL support. 1. Add scrolling to given id related to hash 2. Hash changes won't trigger getInitialProps * Add some comments. * Fix tests. * Add some test cases. * Fire the route cancel event only when needed. (#1316) Earlier we do it for every route change. * Update Koa example for Koa 2 with async/await (#1317) * Release 2.0.0-beta.36 * Update prefetch docs and mention it's production only. (#1324) * fix(package): update friendly-errors-webpack-plugin to version 1.6.0 (#1320) https://greenkeeper.io/ * chore(package): update standard to version 9.0.0 (#1318) https://greenkeeper.io/ * Example with next-routes (#1290) * Example with next-routes * optimize description * rename to with-next-routes * Throw Error when url.parse without true is parsed (#1282) * Throw Error when url.parse without true is parsed This is a bit more descriptive when this mistake is made by the user. * Parse when needed * Parse querystring if it is not provided * With global stylesheet paths (#1327) * with-global-stylesheet without relative paths and with node_modules * a parenthetical remark about material-components-web not being part of the example * Revert "Update friendly-errors-webpack-plugin to the latest version 🚀" (#1328) * chore(package): update husky to version 0.13.2 (#1330) https://greenkeeper.io/ * Fixed some problems with standard (#1331) * Remove unused webpack import in flyfile.js (#1332) * Fix linting errors in standard 9.0 (#1333) * Fix linting errors in standard 9.0 * Update lockfile * fix(package): update unfetch to version 2.1.2 (#1338) https://greenkeeper.io/ * Add a global Promise polyfill. (#1344) * Add a global Promise polyfill. This is because Webpack2 depends on it. * Change the polyfill location. * Add default entries to main.js (#1343) So, we don't need to add them to individual pages. This also fix the issue where, error pages doesn't ping the server. * chore(package): update cross-env to version 3.2.0 (#1348) https://greenkeeper.io/ * Implement preact/inferno SSR (#1346) * Use module-alias to alias preact server side * Use module-alias to alias inferno server side * Remove unneeded routes example * postcss-loader, postcss-easy-import, normalize.css and autoprefixer (#1352) * Add missing ! in using-preact example (#1355) (#1356) * Revert "Update cross-env to the latest version 🚀" (#1358) * Introducing Shallow Routing (#1357) * Simplify route info handling. * Add basic resolve=false support. * Make sure to render getInitialProps always if it's the first render. * Change resolve=false to shallow routing. * Add test cases for shallow routing. * Update README for shallow routing docs. * Update docs. * Update docs. * Update docs. * Update readme.md * fix(package): update loader-utils to version 1.0.3 (#1361) https://greenkeeper.io/ * fix(package): update babel-loader to version 6.4.0 (#1359) https://greenkeeper.io/ * Disable uglify the pretty way (#1351) * fix(package): update send to version 0.15.1 (#1350) https://greenkeeper.io/ * Shallow routing changes (#1363) * Fix a typo in a test suite. * Add old props.url API with warn for all tags. * Update README.md (#1368) Fix graph.cool link in example * Add content based HASH to main.js and common.js (#1336) * Use file hashes instead of BUILD_ID. Now JSON pages also not prefixed with a hash and doesn't support immutable caching. Instead it supports Etag bases caching. * Remove appUpdated Router Events hook. Becuase now we don't need it because there's no buildId validation. * Remove buildId generation. * Turn off hash checks in the dev mode. * Update tests. * Revert "Remove buildId generation." This reverts commit fdd36a5. * Bring back the buildId validation. * Handle buildId validation only in production. * Add BUILD_ID to path again. * Remove duplicate immutable header. * Fix tests. * update yarn * send credentials when fetching new route (#1371) * [WIP] Improve test setup (#1372) * Run tests serially. * Make test result verbose. * Don't wait until closing the browser. * Add some debug logs. * Add bailing support. * Get the browser with a timeout. * Add some comments. * Remove istanbul babel tranformation. Jest already do it and it's breaking our coveralls hit. * Add beforeHistoryChange router event. (#1360) * Fix styled-components server-render example (#1382) * Fix typo (#1380) port 300 -> 3000 * fix(package): update write-file-webpack-plugin to version 4.0.0 (#1383) https://greenkeeper.io/ * chore(package): update chromedriver to version 2.28.0 (#1386) https://greenkeeper.io/ * Ping to on-demand-entries on every page change. (#1384) This will prevent disposing the page after viewing it. Otherwise, it'll possible to dispose the page even we load the page on the client. * Add support for URL objects in Link and Router (#1345) * Add support for URL objects in Link and Router * Fix typo in comment * Fix possible bug if the `href` prop is `null` * Document the usage of URL objects in Link and Router * Update readme.md * Parse URL to get the host & hostname in `isLocal` This should check if the current location and the checked URL have the same `host` or `hostname`. * Format `as` parameter from object to string if required * Format `href` and `as` inside the construct and componentWillReceiveProps * Use `JSON.stringify` to compare objects * Add usage example * chore(package): update chromedriver to version 2.28.0 (#1386) https://greenkeeper.io/ * Refactor the codebase a bit. * Change the example name. * Add a few test cases. * Add the example to the README. * Updated with-apollo example. (#1389) - Deleted several unused dependencies. - Updated dependencies. - Simplified Apollo related imports thanks to react-apollo exporting apollo-client and graphql-tag since [v0.13.2](https://github.com/apollographql/react-apollo/blob/master/Changelog.md#0132). - Tidied the readme and added a link to the Apollo docs. * Use a private Router event API for the ondemand-pinger. (#1397) * Use mitt instead of EventEmitter. (#1398) EventEmitter is quite bit and mitt is a pretty good/small replacement. * Use mitt instead of EventEmitter for the client HMR (#1399) error handling. * fix(package): update babel-plugin-transform-es2015-modules-commonjs to version 6.24.0 (#1400) https://greenkeeper.io/ * chore(package): update husky to version 0.13.3-0 (#1395) https://greenkeeper.io/ * chore(package): update babel-preset-es2015 to version 6.24.0 (#1401) https://greenkeeper.io/ * fix(package): update babel-preset-latest to version 6.24.0 (#1402) https://greenkeeper.io/ * fix(package): update babel-generator to version 6.24.0 (#1404) https://greenkeeper.io/ * fix(package): update babel-core to version 6.24.0 (#1403) https://greenkeeper.io/ * Release 2.0.0-beta.37 * fix(package): update source-map-support to version 0.4.12 (#1405) https://greenkeeper.io/ * Examples: Update Inferno & Preact (#1407) * clean & bump inferno & preact pkgs * reenable UglifyJS for preact * chore(package): update fly-esnext to version 2.0.1 (#1408) https://greenkeeper.io/ * fix(package): update loader-utils to version 1.0.4 (#1411) https://greenkeeper.io/ * chore(package): update cross-env to version 3.2.4 (#1417) https://greenkeeper.io/ * Remove patch-react.js (#1420) This is a pretty complex code base and it cause issues for some React components. And React/fiber is coming with a proper solution. * Release 2.0.0-beta.38 * Upgrade styled-components. Fixes #1416 (#1422) * Update with-apollo example (#1394) * Add minimal apollo example * Update apollo example README * Update apollo example demo link in README * Fix button styles * Fix show more button * Alias demo url * Include the data field on the Apollo store when hydrating * Revert * Include the data field on the Apollo store when hydrating per tpreusse's suggestion. * Add example to faq section in README * Sort by newest; Add active state to buttons * Make optimization suggestions * Use process.browser; inline props * Pass wrapped component's initial props into component heirarchy if they exist * Remove unnecessary sorting of array * Update Apollo example * Remove trailing comma * Update reduxRootKey * Remove unnecessary babelrc * Update with-apollo example - Remove use of deprecated 'reduxRootKey' option - Add loading indicator inside pagination button * Add/link replace (#1419) * Using developit/unfetch as the Fetch API polyfill * Added the replace prop into the Link component * Added integration test for replace prop on Link component * Use jsonPageRes instead of xhr (#1424) * Add reference to deployment wiki page (#1423) * Fix deployment wiki link. * Fix typo in README (#1427) `routing`not `routig` * Example to create next application with scoped/external css. (#1340) * First structure for external css example * Remove: Builded files * Fix: Identation to 2 spaces * Fix example * Fix lint * Fix: Review points * An example with react-helmet (#1264) * upload example * fix * fix * fix * fix .babelrc * fix standard style * fix indent * rename helmetHead to helmet * added gitignore * package.json * removed yarn.lock * Added more examples of using react-helmet * removed gitignore * [POC] Pretty url routing (#1001) * [example] with pretty url routing * use single quotes even in React components * improve Link import * examples: add `svg-components` (#982) * Remove .DS_Store file from helmet example (#1435) * Document babel caching (#1432) * Update readme to reflect latest changes * Remove deprecated methods
|
@timneutkens merged. Short on time today, I haven't looked at the changes. Does this include fixes to @rauchg's requests? Let me know if I can do anything else here. 💟 |
|
@nikvm yeah it includes those. I'm curious what conflicts it has now :( |
|
Going to close this. We should port some of it at a later point. |
I tried to improve the docs under the following premises:
What's missing:
next init)Honestly, once started, I got carried away and might have gone a bit overboard with the changes.
But what's done is done and I might as well share what I've got.
As always, these are suggestions: Keep what you like, discard the rest. ❤️
ℹ️ View the updated
readme.mdhere.Fixes #1134
Fixes #1069