From 007ac302a9f2ee40c270e8418fd3ec38e48dc5a5 Mon Sep 17 00:00:00 2001 From: Brent Jackson Date: Sat, 23 Jun 2018 21:54:39 -0400 Subject: [PATCH] Edit docs --- docs/JSX.md | 19 +++++ docs/_app.js | 4 +- docs/components/LiveEditor.md | 17 ++++ docs/components/LivePreview.md | 17 ++++ docs/components/SidebarLayout.md | 134 +++++++++++++++++++++++++++++++ docs/custom-app.md | 27 +++++++ docs/exporting.md | 2 + docs/mdx.md | 3 + src/entry.js | 2 +- 9 files changed, 222 insertions(+), 3 deletions(-) create mode 100644 docs/JSX.md create mode 100644 docs/components/LiveEditor.md create mode 100644 docs/components/LivePreview.md create mode 100644 docs/components/SidebarLayout.md diff --git a/docs/JSX.md b/docs/JSX.md new file mode 100644 index 0000000..b1f5e63 --- /dev/null +++ b/docs/JSX.md @@ -0,0 +1,19 @@ +--- +--- + +# Using JSX + +x0 supports Compositor JSX format, which allows writing files as pure JSX without any JavaScript syntax. + +```jsx +--- +title: JSX Example +--- +import { Box, Heading } from 'rebass' + + + + Hello + + +``` diff --git a/docs/_app.js b/docs/_app.js index c52a231..23d78e3 100644 --- a/docs/_app.js +++ b/docs/_app.js @@ -18,7 +18,8 @@ const navOrder = [ 'getting-started', 'markdown', 'react', - 'mdx', + 'MDX', + 'JSX', 'custom-app', 'routing', 'components', @@ -32,7 +33,6 @@ const navOrder = [ ] const pageNames = { index: 'Home', - mdx: 'MDX', 'cli-options': 'CLI Options' } diff --git a/docs/components/LiveEditor.md b/docs/components/LiveEditor.md new file mode 100644 index 0000000..cd89867 --- /dev/null +++ b/docs/components/LiveEditor.md @@ -0,0 +1,17 @@ + +# LiveEditor + +The LiveEditor component can be used in React components outside of markdown code fences. +When used within a [ScopeProvider](ScopeProvider) component, there's no need to pass a custom `scope` object. + +```jsx +import React from 'react' +import { LiveEditor } from '@compositor/x0/components' + +const code = `` + +export default props => + +``` diff --git a/docs/components/LivePreview.md b/docs/components/LivePreview.md new file mode 100644 index 0000000..3d5b87d --- /dev/null +++ b/docs/components/LivePreview.md @@ -0,0 +1,17 @@ + +# LivePreview + +The LivePreview component can be used in React components outside of markdown code fences. +When used within a [ScopeProvider](ScopeProvider) component, there's no need to pass a custom `scope` object. + +```jsx +import React from 'react' +import { LivePreview } from '@compositor/x0/components' + +const code = `` + +export default props => + +``` diff --git a/docs/components/SidebarLayout.md b/docs/components/SidebarLayout.md new file mode 100644 index 0000000..7ffcc1d --- /dev/null +++ b/docs/components/SidebarLayout.md @@ -0,0 +1,134 @@ + +# SidebarLayout + +The SidebarLayout component can be used to quickly create a documentation site with navigation. +This site uses the SidebarLayout component for navigation and pagination in the documentation section. + +To use the component, import it in a [custom App](/custom-app). + +```jsx +import React from 'react' +import { SidebarLayout } from '@compositor/x0/components' + +export default props => + +``` + +## Customizing navigation + +The `props.routes` array can be altered to customize the order, names, and other aspects of the navigation. + +### Sorting the routes + +By default the `routes` array is in alphabetical order, with index pages occuring first. +To sort the array for display in navigation, pass a new `routes` prop to the SidebarLayout component. + +```jsx +import React from 'react' +import { SidebarLayout } from '@compositor/x0/components' +import sortBy from 'lodash.sortby' + +const navOrder = [ + 'index', + 'getting-started', + 'api' +] + +export default props => { + const sortedRoutes = sortBy(props.routes, route => { + const i = navOrder.indexOf(route.name) + return i + }) + + return ( + + ) +} +``` + +### Customizing Route Names + +By default the layout will format the filename by capitalizing each word and removing hyphens. +To customize the name of the routes for navigation, pass a new `routes` prop to the SidebarLayout component. + +```jsx +import React from 'react' +import { SidebarLayout } from '@compositor/x0/components' +import sortBy from 'lodash.sortby' + +const routeNames = { + index: 'Home', + api: 'API' +} + +export default props => { + const renamedRoutes = props.routes.map(route => { + if (!routeNames[route.name]) return route + return { + ...route, + name: routeNames[route.name] + } + }) + + return ( + + ) +} +``` + +## Full Width Pages + +The SidebarLayout component will center the contents of the page by default. +To make a page span the full width of the main column, set the `fullWidth` option in default props or front-matter. + +```md +--- +fullWidth: true +--- + +# Full-width markdown page +``` + +```jsx +import React from 'react' + +export default class extends React.Component { + static defaultProps = { + fullWidth: true + } + + render () { + return ( +

Full-width component

+ ) + } +} +``` + +## Page-Specific Layouts + +Custom layouts can be specified as front-matter or default props, then handled in a custom App component to control the layout for specific pages. + +```jsx +// example with custom layouts +import React from 'react' +import { SidebarLayout } from '@compositor/x0/components' +import HomeLayout from './_home-layout.js' + +export default props => { + const { route } = this.props + const { layout } = route.props + + const Layout = layout === 'home' ? HomeLayout : SidebarLayout + + return +} +``` + + diff --git a/docs/custom-app.md b/docs/custom-app.md index 2e0ed4d..ed80d10 100644 --- a/docs/custom-app.md +++ b/docs/custom-app.md @@ -97,3 +97,30 @@ export default class extends React.Component { } } ``` + +## Props + +Custom Apps receive the following props, which can expose greater control over the rendering. + +- `children`: rendered content of the page +- `Component`: a component to pass props to the current route and render content +- `routes`: an array of route objects for the entire site – can be used for rendering navigation +- `route`: the current route object +- The [React Router][react-router] state is also passed to the App + +### Route Object + +Routes include the following properties: + +- `key`: the filepath from webpack's `require.context` +- `name`: the basename of the file +- `path`: path used for routing +- `extname`: file extension +- `dirname`: file directory +- `exact`: (boolean) added to index pages for React Router +- `module`: the JS module for the file +- `Component`: the default export from the file +- `props`: default props or front-matter specified in the file + +[react-router]: https://github.com/ReactTraining/react-router + diff --git a/docs/exporting.md b/docs/exporting.md index 8788e3a..c3c6c22 100644 --- a/docs/exporting.md +++ b/docs/exporting.md @@ -1,2 +1,4 @@ # Exporting + + diff --git a/docs/mdx.md b/docs/mdx.md index 169ba58..aa4b7f6 100644 --- a/docs/mdx.md +++ b/docs/mdx.md @@ -5,6 +5,9 @@ x0 also supports [MDX][mdx] format out of the box. MDX allows you to mix markdown syntax with JSX to render React components. ```mdx +--- +title: MDX Example +--- import { Box } from 'rebass' # Hello diff --git a/src/entry.js b/src/entry.js index dc07be8..5c76d75 100644 --- a/src/entry.js +++ b/src/entry.js @@ -98,7 +98,7 @@ export const getRoutes = async (components = initialComponents) => { const RouterState = withRouter(({ render, ...props }) => { const { pathname } = props.location - const route = props.routes.find(r => r.path === pathname || r.href === pathname) + const route = props.routes.find(r => r.path === pathname || r.href === pathname) || { props: {} } return render({ ...props, route }) })