From 924aada30b3010b9d6ce3aca4b735e29d55be87a Mon Sep 17 00:00:00 2001 From: Pedro Nauck Date: Thu, 18 Jul 2019 12:35:51 -0400 Subject: [PATCH] docs: some adjustments --- MIGRATION_GUIDE.md | 54 +++++++++----------------------- core/gatsby-theme-docz/README.md | 31 ++++++------------ 2 files changed, 24 insertions(+), 61 deletions(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 7ed80bb18..17c5a7b51 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -1,21 +1,12 @@ # Migration Guide - -The [v2 release](https://github.com/pedronauck/docz/pull/950) is our biggest release in terms of changes on our core scripts. -Our bundler system was entirely modified in order to use Gatsby as default bundler and you will need to update -your code if you're coming from a previous version. It's not a big deal, but you need to follow this guide in order to get Docz running -properly on your project after the upgrade. +The [v2 release](https://github.com/pedronauck/docz/pull/950) is our biggest release in terms of changes on our core scripts. Our bundler system was entirely modified in order to use Gatsby as default bundler and you will need to update your code if you’re coming from a previous version. It’s not a big deal, but you need to follow this guide in order to get Docz running properly on your project after the upgrade. ## Gatsby as default bundler +The biggest change in the new v2 is that now our core is entirely build using Gatsby behind the scenes. This is a huge win for Docz, since now we can focus on build new features instead of handling with a lot of bundlers issues (our biggest bottleneck) and enjoy all Gatsby ecosystem. -The biggest change in the new v2 is that now our core is entirely build using Gatsby behind the scenes. -This is a huge win for Docz, since now we can focus on build new features instead of handling with -a lot of bundlers issues (our biggest bottleneck) and enjoy all Gatsby ecosystem. - -So, in order to refactoring our core, we need to change a lot of things and remove others that no longer make sense. -The most expressive changes here is about the configuration for `doczrc.js` and the plugin system. +So, in order to refactoring our core, we need to change a lot of things and remove others that no longer make sense. The most expressive changes here is about the configuration for `doczrc.js` and the plugin system. ### List of removed properties from `doczrc.js` - * **`websocketHost`** ▶︎ _no longer need_ * **`websocketPort`** ︎︎︎▶︎ _no longer need_ * **`wrapper`** ▶︎ _removed_ @@ -27,7 +18,6 @@ The most expressive changes here is about the configuration for `doczrc.js` and * **`modifyBabelRc`** ▶︎ use Gatsby [`onCreateBabelConfig`](https://www.gatsbyjs.org/docs/node-apis/#onCreateBabelConfig) hook ## New hooks for plugins - The `createPlugin` method also changed in order to fit with Gatsby now. ### List of removed/changed properties from `createPlugin()` @@ -44,42 +34,28 @@ The `createPlugin` method also changed in order to fit with Gatsby now. > You can have more details about then [here](https://www.gatsbyjs.org/docs/node-apis). ## `docz-theme-default` removed +The main reason that made us change our core to use Gatsby is that now it have a feature called themes. In the last major version we launched our own `gatsby-theme-docz` and this was impressive since we could use Docz inside a Gatsby project and brings a lot of new possibilites when creating a documentation. -The main reason that made me want to change our core to use Gatsby is that now it have a feature called themes. -In the last major version we launched our own `gatsby-theme-docz` and this was impressive since we could use Docz -inside a Gatsby project and brings a lot of new possibilites when creating a documentation. - -So, indeed we were using Gatsby theme at all, but in the wrong way. One of the best benefits of Gatsby theme are -the feature called Component Shadowing, that's the hability to replace theme files just by creating your own file following a file naming convetion. -This is awesome and is something that people always ask for me, like: "I want just to change the head in the Docz theme". +So, indeed we were using Gatsby theme at all, but in the wrong way. One of the best benefits of Gatsby theme are the feature called Component Shadowing, that’s the ability to replace theme files just by creating your own file following a file naming convention. This is awesome and is something that people always ask for me, like: “I want just to change the head in the Docz theme”. -In order to get Docz running with component shadowing we removed `docz-theme-default` and now you don't need to install it anymore. -You can just add `docz` and your project is done +In order to get Docz running with component shadowing we removed `docz-theme-default` and now you don’t need to install it anymore. You can just add `docz` and your project is done. -Check [here]() readme for more information. +Check [here](h) readme for more information. ### Code highlight with PrismJS +In the last version of Docz we’re using Codemirror to highlight code inside `` and code blocks. Now we are using [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) together with Theme UI. -In the last version of Docz we're using Codemirror to highlight code inside `` and code blocks. -Now we are using [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) together with Theme UI. - -Check [here]() for more information. +Check [here](h) for more information. ### New `themeConfig` properties +Another great thing launched in the newest version is the integration with the [Theme UI](https://theme-ui.com). Theme UI it’s a library for build consistent, themeable React apps based on constraint-based design principles. So, in order to integration it with our new theme, a lot of changes are made inside the `themeConfig` object. -Another great thing launched in the newest version is the integration with the [Theme UI](https://theme-ui.com). -Theme UI it's a library for build consistent, themeable React apps based on constraint-based design principles. -So, in order to integration it with our new theme, a lot of changes are made inside the `themeConfig` object. - -Check [here]() for more information. +Check [here](h) for more information. ## `theme` property removed +The property used to define your Docz theme inside the `doczrc.js` was removed. But you can still create and use your own theme from scratch if you want. -The property used to define your Docz theme inside the `doczrc.js` was removed. But you can still -create and use your own theme from scratch if you want. - -If you want to use your own theme, just create a file called `src/gatsby-theme-docz/index.js` in order -to use component shadowing and replace it with your new theme. +If you want to use your own theme, just create a file called `src/gatsby-theme-docz/index.js` in order to use component shadowing and replace it with your new theme. ```js // src/gatsby-theme-docz/index.js @@ -92,9 +68,7 @@ export default (props) => Check [here](https://www.docz.site/docs/creating-themes) for more information about how to create themes. ## `wrapper` property removed - -The same thing happened here for the oldest `wrapper` property. Now you can wrap your entire application -by just creating a file called `src/gatsby-theme-docz/wrapper.js` +The same thing happened here for the oldest `wrapper` property. Now you can wrap your entire application by just creating a file called `src/gatsby-theme-docz/wrapper.js` ```js // src/gatsby-theme-docz/index.js diff --git a/core/gatsby-theme-docz/README.md b/core/gatsby-theme-docz/README.md index d823734f0..3bb72d7e7 100644 --- a/core/gatsby-theme-docz/README.md +++ b/core/gatsby-theme-docz/README.md @@ -21,8 +21,7 @@ module.exports = { ### Configuration -Set your config by using `doczrc.js` file ([see all available](https://www.docz.site/docs/project-configuration)) or if you want to -set some defaults for your theme, use `options` on plugin definition: +Set your config by using `doczrc.js` file ([see all available](https://www.docz.site/docs/project-configuration)) or if you want to set some defaults for your theme, use `options` on plugin definition: ```js // gatsby-config.js @@ -53,16 +52,13 @@ export default { ### Customizing components -Components shadowing is one of the best things included in the new Gatsby theme feature, with it is possible to replace -theme files just by creating your own file following a file naming convetion. +Components shadowing is one of the best things included in the new Gatsby theme feature, with it is possible to replace theme files just by creating your own file following a file naming convention. -Example: If you're using our `gatsby-theme-docz` which has a `Header` component located at `src/components/Header/index.js` -you can override the component by creating `src/gatsby-theme-docz/components/Header/index.js`. Cool right? +Example: If you're using our `gatsby-theme-docz` which has a `Header` component located at `src/components/Header/index.js` you can override the component by creating `src/gatsby-theme-docz/components/Header/index.js`. Cool right? ### Adding your logo -So, now that you know about how component shadowing works on Gatsby themes, if you don't want to override the entire `
` component -but just change your logo inside it, your can shadow the `` component used in the header just by creating your own at `src/gatsby-theme-docz/components/Logo/index.js` +So, now that you know about how component shadowing works on Gatsby themes, if you don't want to override the entire `
` component but just change your logo inside it, your can shadow the `` component used in the header just by creating your own at `src/gatsby-theme-docz/components/Logo/index.js` ```js // src/gatsby-theme-docz/components/Logo/index.js @@ -76,9 +72,7 @@ Easy, right? ### Creating your own Docz theme -One of the coolest thing of Docz is that you can create your own theme if you want from scratch and use all benefits of it. -The oldest way to acomplish that is by using the `theme` property inside the `doczrc.js` file. Now, if you want to create -your own theme, just create a file located at `src/gatsby-theme-docz/index.js` +One of the coolest thing of Docz is that you can create your own theme if you want from scratch and use all benefits of it. The oldest way to acomplish that is by using the `theme` property inside the `doczrc.js` file. Now, if you want to create your own theme, just create a file located at `src/gatsby-theme-docz/index.js` ```js import React from 'react' @@ -118,8 +112,7 @@ export default theme(themeConfig)(Theme) ### Wrapping the entire app -Sometime you need to wrap your entire application in order to add some `Provider` or just to load some script. -You can do this easily inside our theme by creating a file located at `src/gatsby-theme-docz/wrapper.js` +Sometime you need to wrap your entire application in order to add some `Provider` or just to load some script. You can do this easily inside our theme by creating a file located at `src/gatsby-theme-docz/wrapper.js` ```js // src/gatsby-theme-docz/index.js @@ -135,10 +128,9 @@ export default ({ children }) => ( ## Theme UI integrated -As default theme systeAs default theme system we are using the [Theme-UI](https://theme-ui.com/), it's a library for build consistent, themeable React apps -based on constraint-based design principles. +As default theme system we are using the [Theme-UI](https://theme-ui.com/), it's a library for build consistent, themeable React apps based on constraint-based design principles. -You can modify our based theme creating your own style, combining these modifications with the component shadowing and creating a totally differente documentation. +You can modify our based theme creating your own style, combining these modifications with the component shadowing and creating a totally different documentation. Check our [base theme object](https://github.com/pedronauck/docz/blob/feat/gatsby/core/gatsby-theme-docz/src/theme/index.js) to see the properties. @@ -174,8 +166,7 @@ export default merge(baseTheme, { ### Changing code highlight -Both code highlights shortcodes and the `` component are using [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight the code. -If you want to modify and use another PrismJS theme, you can do that just passing a `prismTheme` property for your theme. +Both code highlights shortcodes and the `` component are using [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight the code. If you want to modify and use another PrismJS theme, you can do that just passing a `prismTheme` property for your theme. ```js // doczrc.js @@ -226,9 +217,7 @@ export default { ## Getting data -Using our Gatsby Theme you can enjoy all our hooks to get data for your pages and also get data from Gatsby. -So, you can create isolated pages on Gatsby using gatsby pages and get data from Docz or maybe pass data -for your Docz documents using source from gatsby. +Using our Gatsby Theme you can enjoy all our hooks to get data for your pages and also get data from Gatsby. So, you can create isolated pages on Gatsby using gatsby pages and get data from Docz or maybe pass data for your Docz documents using source from gatsby. Imagine, that you have your home page inside `/pages` and you want to show all documents parsed from Docz. You can easy get this by doing: