diff --git a/docs-tool/.gitignore b/docs-tool/.gitignore new file mode 100644 index 0000000000000..d30f40ef4422f --- /dev/null +++ b/docs-tool/.gitignore @@ -0,0 +1,21 @@ +# See https://help.github.com/ignore-files/ for more about ignoring files. + +# dependencies +/node_modules + +# testing +/coverage + +# production +/build + +# misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local + +npm-debug.log* +yarn-debug.log* +yarn-error.log* diff --git a/docs-tool/bin/build.js b/docs-tool/bin/build.js new file mode 100644 index 0000000000000..242187b662d79 --- /dev/null +++ b/docs-tool/bin/build.js @@ -0,0 +1,15 @@ +#!/usr/bin/env node +const path = require( 'path' ); +const extendsConfig = require( './helpers/extend-webpack-config' ); +const usersCwd = process.cwd(); + +// webpack.config.prod.js checks this. +process.env.NODE_ENV = 'production'; + +// Load and edit the create-react-app config. +process.chdir( path.resolve( __dirname, '../' ) ); +const webpackConfig = require( 'react-scripts/config/webpack.config.prod' ); +extendsConfig( webpackConfig, usersCwd ); + +// Run the build. +require( 'react-scripts/scripts/build' ); diff --git a/docs-tool/bin/helpers/extend-webpack-config.js b/docs-tool/bin/helpers/extend-webpack-config.js new file mode 100644 index 0000000000000..e590903b864c0 --- /dev/null +++ b/docs-tool/bin/helpers/extend-webpack-config.js @@ -0,0 +1,33 @@ +const path = require( 'path' ); + +module.exports = function( webpackConfig, usersCwd ) { + // Adding "glutenberg" alias + webpackConfig.resolve.alias.glutenberg = path.resolve( __dirname, '../../src/config/' ); + + // Loading the config folder + webpackConfig.resolve.alias.config = path.resolve( usersCwd, process.argv[ 2 ] ); + webpackConfig.resolve.modules = webpackConfig.resolve.modules.concat( [ webpackConfig.resolve.alias.config ] ); + + // Using the user's node_modules + const usersNodeModules = path.resolve( usersCwd, 'node_modules' ); + webpackConfig.resolve.modules = webpackConfig.resolve.modules.concat( [ usersNodeModules ] ); + + // Deleting CRA scoping + webpackConfig.resolve.plugins = []; + webpackConfig.module.rules.forEach( ( rule ) => { + if ( rule.include ) { + rule.include = [ rule.include, webpackConfig.resolve.alias.config ]; + } + } ); + + // Adding the markdown loader and exclude if from the file loader + webpackConfig.module.rules.forEach( rule => { + if ( rule.loader === require.resolve('file-loader') ) { + rule.exclude.push( /\.md/ ); + } + } ); + webpackConfig.module.rules.push( { + test: /\.md/, + use: require.resolve( 'raw-loader' ), + } ); +} diff --git a/docs-tool/bin/start.js b/docs-tool/bin/start.js new file mode 100644 index 0000000000000..7c6774b946e10 --- /dev/null +++ b/docs-tool/bin/start.js @@ -0,0 +1,15 @@ +#!/usr/bin/env node +const path = require( 'path' ); +const extendsConfig = require( './helpers/extend-webpack-config' ); +const usersCwd = process.cwd(); + +// webpack.config.prod.js checks this. +process.env.NODE_ENV = 'development'; + +// Load and edit the create-react-app config. +process.chdir( path.resolve( __dirname, '../' ) ); +const webpackConfig = require( 'react-scripts/config/webpack.config.dev' ); +extendsConfig( webpackConfig, usersCwd ); + +// Run the build. +require( 'react-scripts/scripts/start' ); diff --git a/docs-tool/package.json b/docs-tool/package.json new file mode 100644 index 0000000000000..0f7d2090bffbf --- /dev/null +++ b/docs-tool/package.json @@ -0,0 +1,20 @@ +{ + "name": "docs-tool", + "version": "0.1.0", + "private": true, + "dependencies": { + "prismjs": "^1.6.0", + "react": "^15.6.1", + "react-dom": "^15.6.1", + "react-markdown": "^2.5.0", + "react-router-dom": "^4.1.1", + "react-scripts": "1.0.10" + }, + "scripts": { + "start": "react-scripts start", + "build": "react-scripts build", + "test": "react-scripts test --env=jsdom", + "eject": "react-scripts eject" + }, + "devDependencies": {} +} diff --git a/docs-tool/public/favicon.ico b/docs-tool/public/favicon.ico new file mode 100644 index 0000000000000..5c125de5d897c Binary files /dev/null and b/docs-tool/public/favicon.ico differ diff --git a/docs-tool/public/index.html b/docs-tool/public/index.html new file mode 100644 index 0000000000000..d83c65c2a9125 --- /dev/null +++ b/docs-tool/public/index.html @@ -0,0 +1,42 @@ + + + + + + + + + + + + + React App + + + +
+ + + diff --git a/docs-tool/public/manifest.json b/docs-tool/public/manifest.json new file mode 100644 index 0000000000000..be607e4177191 --- /dev/null +++ b/docs-tool/public/manifest.json @@ -0,0 +1,15 @@ +{ + "short_name": "React App", + "name": "Create React App Sample", + "icons": [ + { + "src": "favicon.ico", + "sizes": "192x192", + "type": "image/png" + } + ], + "start_url": "./index.html", + "display": "standalone", + "theme_color": "#000000", + "background_color": "#ffffff" +} diff --git a/docs-tool/src/App.js b/docs-tool/src/App.js new file mode 100644 index 0000000000000..ad940991e32e2 --- /dev/null +++ b/docs-tool/src/App.js @@ -0,0 +1,37 @@ +import React, { Component } from 'react'; +import { BrowserRouter, Route } from 'react-router-dom'; +import Prism from 'prismjs'; + +import { getStories } from 'glutenberg'; +import Sidebar from './Sidebar'; + +const createPage = ( Comp ) => class extends Component { + componentDidMount( prevProps ) { + Prism.highlightAll(); + } + + render() { + return ; + } +} + +const App = () => { + return ( + +
+
+
+ +
+ { getStories().map( ( { path, Component: Comp }, index ) => ( + + ) ) } +
+
+
+
+ + ); +} + +export default App; diff --git a/docs-tool/src/Sidebar.js b/docs-tool/src/Sidebar.js new file mode 100644 index 0000000000000..71bb973d80695 --- /dev/null +++ b/docs-tool/src/Sidebar.js @@ -0,0 +1,46 @@ +import React from 'react'; +import { Link } from 'react-router-dom'; + +import { getStoriesTree } from 'glutenberg'; + +function MenuItem( { item } ) { + return ( +
  • + { ! item.children.length && { item.title } } + { !! item.children.length && ( +
    + + { item.title } +
    + ) } + { !! item.children.length && ( + + ) } +
    • + ); +} + +function Sidebar() { + return ( +
    +
    + +
    +
    + ); +} + +export default Sidebar; diff --git a/docs-tool/src/config/index.js b/docs-tool/src/config/index.js new file mode 100644 index 0000000000000..267eb16668c58 --- /dev/null +++ b/docs-tool/src/config/index.js @@ -0,0 +1,36 @@ +import React from 'react'; +import ReactMarkdown from 'react-markdown'; + +const stories = []; + +export function addStory( story ) { + const { name, parents = [], markdown } = story; + stories.push( { + path: '/' + parents.concat( name ).join( '/' ), + id: parents.concat( name ).join( '.' ), + parent: parents.join( '.' ), + Component: markdown ? () => : story.Component, + ...story, + } ); +} + +export function getStories() { + return stories; +} + +export function getStoriesTree() { + const buildTreeNode = ( story ) => { + return { + ...story, + children: buildTreeChildren( story.id ), + }; + } + + const buildTreeChildren = ( parentId = '' ) => { + return stories + .filter( ( story ) => story.parent === parentId ) + .map( buildTreeNode ); + }; + + return buildTreeChildren(); +} diff --git a/docs-tool/src/index.js b/docs-tool/src/index.js new file mode 100644 index 0000000000000..dd989ba8d12ae --- /dev/null +++ b/docs-tool/src/index.js @@ -0,0 +1,13 @@ +import React from 'react'; +import ReactDOM from 'react-dom'; +import 'prismjs'; +import 'prismjs/themes/prism.css'; + +import 'config'; + +import App from './App'; +import registerServiceWorker from './registerServiceWorker'; +import './styles/main.css'; + +ReactDOM.render(, document.getElementById('root')); +registerServiceWorker(); diff --git a/docs-tool/src/registerServiceWorker.js b/docs-tool/src/registerServiceWorker.js new file mode 100644 index 0000000000000..4a3ccf02124e9 --- /dev/null +++ b/docs-tool/src/registerServiceWorker.js @@ -0,0 +1,108 @@ +// In production, we register a service worker to serve assets from local cache. + +// This lets the app load faster on subsequent visits in production, and gives +// it offline capabilities. However, it also means that developers (and users) +// will only see deployed updates on the "N+1" visit to a page, since previously +// cached resources are updated in the background. + +// To learn more about the benefits of this model, read https://goo.gl/KwvDNy. +// This link also includes instructions on opting out of this behavior. + +const isLocalhost = Boolean( + window.location.hostname === 'localhost' || + // [::1] is the IPv6 localhost address. + window.location.hostname === '[::1]' || + // 127.0.0.1/8 is considered localhost for IPv4. + window.location.hostname.match( + /^127(?:\.(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}$/ + ) +); + +export default function register() { + if (process.env.NODE_ENV === 'production' && 'serviceWorker' in navigator) { + // The URL constructor is available in all browsers that support SW. + const publicUrl = new URL(process.env.PUBLIC_URL, window.location); + if (publicUrl.origin !== window.location.origin) { + // Our service worker won't work if PUBLIC_URL is on a different origin + // from what our page is served on. This might happen if a CDN is used to + // serve assets; see https://github.com/facebookincubator/create-react-app/issues/2374 + return; + } + + window.addEventListener('load', () => { + const swUrl = `${process.env.PUBLIC_URL}/service-worker.js`; + + if (!isLocalhost) { + // Is not local host. Just register service worker + registerValidSW(swUrl); + } else { + // This is running on localhost. Lets check if a service worker still exists or not. + checkValidServiceWorker(swUrl); + } + }); + } +} + +function registerValidSW(swUrl) { + navigator.serviceWorker + .register(swUrl) + .then(registration => { + registration.onupdatefound = () => { + const installingWorker = registration.installing; + installingWorker.onstatechange = () => { + if (installingWorker.state === 'installed') { + if (navigator.serviceWorker.controller) { + // At this point, the old content will have been purged and + // the fresh content will have been added to the cache. + // It's the perfect time to display a "New content is + // available; please refresh." message in your web app. + console.log('New content is available; please refresh.'); + } else { + // At this point, everything has been precached. + // It's the perfect time to display a + // "Content is cached for offline use." message. + console.log('Content is cached for offline use.'); + } + } + }; + }; + }) + .catch(error => { + console.error('Error during service worker registration:', error); + }); +} + +function checkValidServiceWorker(swUrl) { + // Check if the service worker can be found. If it can't reload the page. + fetch(swUrl) + .then(response => { + // Ensure service worker exists, and that we really are getting a JS file. + if ( + response.status === 404 || + response.headers.get('content-type').indexOf('javascript') === -1 + ) { + // No service worker found. Probably a different app. Reload the page. + navigator.serviceWorker.ready.then(registration => { + registration.unregister().then(() => { + window.location.reload(); + }); + }); + } else { + // Service worker found. Proceed as normal. + registerValidSW(swUrl); + } + }) + .catch(() => { + console.log( + 'No internet connection found. App is running in offline mode.' + ); + }); +} + +export function unregister() { + if ('serviceWorker' in navigator) { + navigator.serviceWorker.ready.then(registration => { + registration.unregister(); + }); + } +} diff --git a/docs-tool/src/styles/main.css b/docs-tool/src/styles/main.css new file mode 100644 index 0000000000000..c94c58da76b1b --- /dev/null +++ b/docs-tool/src/styles/main.css @@ -0,0 +1,16 @@ +body { + margin: 0; +} + +#secondary { + padding: 4rem 0 0; +} + +code { + tab-size: 4; +} + +:not(pre) > code[class*="language-"], +pre[class*="language-"] { + background-color: #f7f7f7 !important; +} diff --git a/docs/blocks-basic.md b/docs/blocks-basic.md new file mode 100644 index 0000000000000..7dc13531811f2 --- /dev/null +++ b/docs/blocks-basic.md @@ -0,0 +1,37 @@ +# Writing your first block + +```js +// block.js (ES5) +var el = wp.element.createElement; +var blockStyle = { backgroundColor: '#900', color: '#fff', padding: '20px' }; + +wp.blocks.registerBlockType( 'mytheme/block', { + title: 'Hello World (step 1)', + icon: 'universal-access-alt', + category: 'layout', + edit: function() { + return el( 'p', { style: blockStyle }, 'Hello World' ); + }, + save: function() { + return el( 'p', { style: blockStyle }, 'Hello World' ); + }, +} ); +``` + +```js +// block.js (ESnext) +const { registerBlockType } = wp.blocks; +const blockStyle = { backgroundColor: '#900', color: '#fff', padding: '20px' }; + +registerBlockType( 'mytheme/block', { + title: 'Hello Block', + icon: 'universal-access-alt', + category: 'layout', + edit() { + return
    Hello World
    ; + }, + save() { + return
    Hello World
    ; + }, +} ); +``` diff --git a/docs/blocks-editable.md b/docs/blocks-editable.md new file mode 100644 index 0000000000000..6f078b090f685 --- /dev/null +++ b/docs/blocks-editable.md @@ -0,0 +1 @@ +# Editable block diff --git a/docs/blocks-stylesheet.md b/docs/blocks-stylesheet.md new file mode 100644 index 0000000000000..832c38cd53d30 --- /dev/null +++ b/docs/blocks-stylesheet.md @@ -0,0 +1,65 @@ +# Adding a stylesheet + +```js +// block.js (ES5) +var el = wp.element.createElement; + +wp.blocks.registerBlockType( 'mytheme/block', { + title: 'Hello World (step 2)', + icon: 'universal-access-alt', + category: 'layout', + edit: function( props ) { + return el( 'p', { className: props.className }, 'Hello World' ); + }, + save: function() { + return el( 'p', 'Hello World' ); + }, +} ); +``` + +```js +// block.js (ESnext) +const { registerBlockType } = wp.blocks; + +registerBlockType( 'mytheme/block', { + title: 'Hello Block', + icon: 'universal-access-alt', + category: 'layout', + edit( { className } ) { + return
    Hello World
    ; + }, + save() { + return
    Hello World
    ; + }, +} ); +``` + +```css +/* style.css */ + +/** + * Note that these styles are loaded *before* editor styles, so that + * editor-specific styles using the same selectors will take precedence. + */ +.wp-block-mytheme-block { + color: darkred; + background: #fcc; + border: 2px solid #c99; + padding: 20px; +} +``` + +```css +/* editor.css */ + +/** + * Note that these styles are loaded *after* common styles, so that + * editor-specific styles using the same selectors will take precedence. + */ +.wp-block-mytheme-block { + color: green; + background: #cfc; + border: 2px solid #9c9; + padding: 20px; +} +``` diff --git a/docs/blocks.md b/docs/blocks.md new file mode 100644 index 0000000000000..54e0a5ff9fea2 --- /dev/null +++ b/docs/blocks.md @@ -0,0 +1 @@ +# Blocks diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 0000000000000..55afe27762232 --- /dev/null +++ b/docs/readme.md @@ -0,0 +1,13 @@ +# Introduction + +"Gutenberg" is the codename for the 2017 WordPress editor focus. The goal if this focus is to create a new post and page editing experience that makes it easy for anyone to create rich post layouts. This was the kickoff goal: + +> The editor will endeavour to create a new page and post building experience that makes writing rich posts effortless, and has “blocks” to make it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery. + +Key take-aways from parsing that paragraph: + +- Authoring richly laid out posts is a key strength of WordPress. +- By embracing "the block", we can potentially unify multiple different interfaces into one. Instead of learning how to write shortcodes, custom HTML, or paste URLs to embed, you should do with just learning the block, and all the pieces should fall in place. +- "Mystery meat" refers to hidden features in software, features that you have to discover. WordPress already supports a large amount of blocks and 30+ embeds, so let's surface them. + +Gutenberg is being developed on [GitHub](https://github.com/WordPress/gutenberg), and you can try [an early beta version today from the plugin repository](https://wordpress.org/plugins/gutenberg/). Though keep in mind it's not fully functional, feature complete, or production ready. diff --git a/docs/stories/index.js b/docs/stories/index.js new file mode 100644 index 0000000000000..3dd5336f50481 --- /dev/null +++ b/docs/stories/index.js @@ -0,0 +1,47 @@ +import { addStory } from 'glutenberg'; + +import intro from '../readme.md'; +import faq from '../faq.md'; +import step1 from '../blocks-basic.md'; +import step2 from '../blocks-stylesheet.md'; +import step3 from '../blocks-editable.md'; + +addStory( { + name: 'intro', + title: 'Introduction', + path: '/', + markdown: intro, +} ); + +addStory( { + name: 'faq', + title: 'FAQ', + markdown: faq, +} ); + +addStory( { + name: 'blocks', + title: 'Creating Blocks', + markdown: '# Creating Blocks', +} ); + +addStory( { + parents: [ 'blocks' ], + name: 'step1', + title: 'Step 1', + markdown: step1, +} ); + +addStory( { + parents: [ 'blocks' ], + name: 'step2', + title: 'Step 2', + markdown: step2, +} ); + +addStory( { + parents: [ 'blocks' ], + name: 'step3', + title: 'Step 3', + markdown: step3, +} );