Bootstrap a documentation website tailored towards the usage of Guten…

…berg outside WordPress (WordPress#54375)

Co-authored-by: Marin Atanasov <[email protected]>
Co-authored-by: Ramon <[email protected]>
Co-authored-by: Aki Hamano <[email protected]>

.npmpackagejsonlintrc.json

@@ -29,6 +29,14 @@
 				"require-repository-directory": "off",
 				"prefer-no-devDependencies": "off"
 			}
+		},
+		{
+			"patterns": [ "./platform-docs/package.json" ],
+			"rules": {
+				"require-publishConfig": "off",
+				"require-repository-directory": "off",
+				"prefer-no-devDependencies": "off"
+			}
 		}
 	]
 }

platform-docs/.eslintrc.js

@@ -0,0 +1,21 @@
+module.exports = {
+	root: true,
+	plugins: [ 'react' ],
+	extends: [ 'plugin:@wordpress/eslint-plugin/recommended' ],
+	settings: {
+		react: {
+			pragma: 'React',
+			version: 'detect',
+			flowVersion: '0.92.0',
+		},
+		'import/resolver': require.resolve( '../tools/eslint/import-resolver' ),
+	},
+	overrides: [
+		{
+			files: [ '**/*.js' ],
+			rules: {
+				'import/no-unresolved': 'off',
+			},
+		},
+	],
+};

platform-docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

platform-docs/README.md

@@ -0,0 +1,25 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ npm install
+```
+
+### Local Development
+
+```
+$ npm run start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ npm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.

platform-docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+	presets: [ require.resolve( '@docusaurus/core/lib/babel/preset' ) ],
+};

platform-docs/docs/advanced/_category_.json

@@ -0,0 +1,10 @@
+{
+	"position": 4,
+	"label": "Advanced",
+	"collapsible": true,
+	"collapsed": true,
+	"link": {
+		"type": "generated-index",
+		"title": "Advanced"
+	}
+}

platform-docs/docs/advanced/create-format.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 1
+---
+
+# Create a RichText format

platform-docs/docs/advanced/dynamic.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 3
+---
+
+# Augmenting blocks

platform-docs/docs/advanced/interactivity.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 2
+---
+
+# Interactivity API

platform-docs/docs/advanced/wordpress.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 4
+---
+
+# Gutenberg and WordPress

platform-docs/docs/basic-concepts/_category_.json

@@ -0,0 +1,10 @@
+{
+    "position": 2,
+	"label": "Basic Concepts",
+	"collapsible": true,
+	"collapsed": false,
+	"link": {
+		"type": "generated-index",
+		"title": "Basic Concepts"
+	}
+}

platform-docs/docs/basic-concepts/data.md

@@ -0,0 +1,119 @@
+---
+sidebar_position: 2
+---
+
+# Data Format
+
+A block editor document is a collection of semantically consistent descriptions of what each block is and what its essential data is.
+
+The input and output of the block editor is a tree of block objects with the current format:
+
+```js
+const value = [ block1, block2, block3 ];
+```
+
+### The block object
+
+Each block object has an id, a set of attributes and potentially a list of child blocks.
+
+```js
+const block = {
+	clientId, // unique string identifier.
+	type, // The block type (paragraph, image...)
+	attributes, // (key, value) set of attributes representing the direct properties/content of the current block.
+	innerBlocks, // An array of child blocks or inner blocks.
+};
+```
+
+Note the attributes keys and types, the allowed inner blocks are defined by the block type. For example, the core quote block has a `cite` string attribute representing the cite content while a heading block has a numeric `level` attribute, representing the level of the heading (1 to 6).
+
+During the lifecycle of the block in the editor, the block object can receive extra metadata:
+
+-   `isValid`: A boolean representing whether the block is valid or not;
+-   `originalContent`: The original HTML serialization of the block.
+
+**Examples**
+
+```js
+// A simple paragraph block.
+const paragraphBlock1 = {
+	clientId: '51828be1-5f0d-4a6b-8099-f4c6f897e0a3',
+	type: 'core/paragraph',
+	attributes: {
+		content: 'This is the <strong>content</strong> of the paragraph block',
+		dropCap: true,
+	},
+};
+
+// A separator block.
+const separatorBlock = {
+	clientId: '51828be1-5f0d-4a6b-8099-f4c6f897e0a4',
+	type: 'core/separator',
+	attributes: {},
+};
+
+// A columns block with a paragraph block on each column.
+const columnsBlock = {
+	clientId: '51828be1-5f0d-4a6b-8099-f4c6f897e0a7',
+	type: 'core/columns',
+	attributes: {},
+	innerBlocks: [
+		{
+			clientId: '51828be1-5f0d-4a6b-8099-f4c6f897e0a5',
+			type: 'core/column',
+			attributes: {},
+			innerBlocks: [ paragraphBlock1 ],
+		},
+		{
+			clientId: '51828be1-5f0d-4a6b-8099-f4c6f897e0a6',
+			type: 'core/column',
+			attributes: {},
+			innerBlocks: [ paragraphBlock2 ],
+		},
+	],
+};
+```
+
+## HTML serialization and parsing
+
+While block editors powered by Gutenberg manipulate and edit the content as a JavaScript array of blocks, the Gutenberg framework also offers a way to serialize the blocks into HTML and parse them back.
+
+```js
+import { serialize, parse } from '@wordpress/blocks';
+
+const value = [ block1, block2, block3 ];
+
+const html = serialize( value );
+
+const parsedValue = parse( html ); // This should be equivalent to value.
+```
+
+### Delimiters and Parsing Expression Grammar
+
+In order to keep the metadata of the blocks within the serialized HTML, we chose to use HTML comments in order to keep the formality, explicitness, and unambiguity in the existing HTML syntax.
+
+By storing data in HTML comments, we would know that we wouldn't break the rest of the HTML in the document, that browsers should ignore it, and that we could simplify our approach to parsing the document.
+
+Unique to HTML comments is the fact that they cannot legitimately exist in ambiguous places, such as inside of HTML attributes like `<img alt='data-id="14"'>`. Comments are also quite permissive. Whereas HTML attributes are complicated to parse properly, comments are quite easily described by a leading `<!--` followed by anything except `--` until the first `-->`. This simplicity and permissiveness means that the parser can be implemented in several ways without needing to understand HTML properly, and we have the liberty to use more convenient syntax inside of the comment: we only need to escape double-hyphen sequences. We take advantage of this in how we store block attributes: as JSON literals inside the comment.
+
+After running this through the parser, we're left with a simple object we can manipulate idiomatically, and we don't have to worry about escaping or unescaping the data. It's handled for us through the serialization process. Because the comments are so different from other HTML tags and because we can perform a first-pass to extract the top-level blocks, we don't actually depend on having fully valid HTML!
+
+This has dramatic implications for how simple and performant we can make our parser. These explicit boundaries also protect damage to a single block from bleeding into other blocks or tarnishing the entire document. It also allows the system to identify unrecognized blocks before rendering them.
+
+_N.B.:_ The defining aspects of blocks are their semantics and the isolation mechanism they provide: in other words, their identity. On the other hand, where their data is stored is a more liberal aspect. Blocks support more than just static local data (via JSON literals inside the HTML comment or within the block's HTML), and more mechanisms (_e.g._, global blocks or otherwise resorting to storage in complementary `WP_Post` objects) are expected. See [attributes](/docs/reference-guides/block-api/block-attributes.md) for details.
+
+### The Anatomy of a Serialized Block
+
+When blocks are serialized as HTML, their attributes—depending on the nature of the block—are serialized to these explicit comment delimiters.
+
+```html
+<!-- wp:image -->
+<figure class="wp-block-image"><img src="source.jpg" alt="" /></figure>
+<!-- /wp:image -->
+```
+
+A purely dynamic block that is to be server-rendered before display could look like this:
+
+```html
+<!-- wp:latest-posts {"postsToShow":4,"displayPostDate":true} /-->
+```

platform-docs/docs/basic-concepts/internationalization.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 5
+---
+
+# Internationalization

platform-docs/docs/basic-concepts/rendering.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 6
+---
+
+# Rendering blocks

platform-docs/docs/basic-concepts/rich-text.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 4
+---
+
+# RichText and Format Library

platform-docs/docs/basic-concepts/settings.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 3
+---
+
+# Block Editor Settings

platform-docs/docs/basic-concepts/ui.md

@@ -0,0 +1,29 @@
+---
+sidebar_position: 1
+---
+
+# Compose the UI
+
+## Building blocks
+
+The interface of the block editor is composed of several UI elements:
+
+ - The block list is the main area where you can interact and edit the blocks.
+ - The block toolbar: When a block is selected, the main tools to manipulate the blocks are rendered in a block toolbar. This toolbar can be rendered adjacent to the block or separate depending on the design you want to achieve for your block editor.
+ - The block inspector: Generally shown as a sidebar or a modal, the inspector shows advanced tools to manipulate the selected block.
+ - Block inserter: Can be used to select blocks to insert to your block editor.
+
+The Gutenberg platform allows you to render these pieces separately and lay them out as you wish to achieve the desired design for your interface.
+
+## The Block Toolbar
+
+Wrapping your `BlockCanvas` component within the `BlockTools` wrapper allows the editor to render a block toolbar adjacent to the selected block.
+
+## The Block Inspector
+
+You can use the `BlockInspector` to render what is called the block inspector. It's a set of tools that are specific to the selected block.
+While the block toolbar contains what are considered to be the "main tools" to manipulate each block, the block inspector is meant to render advanced tools and customization options. It is generally rendered as a sidebar or a modal.
+
+## The Block Inserter
+
+By default the block editor renders a block inserter at the end of the canvas if there's no block selected. It also renders an inserter if you hover over the area between two consecutive blocks. That said, you can also decide to render a permanent inserter, for instance in a header of your editor. You can do so by using the `Inserter` component.

platform-docs/docs/create-block/_category_.json

@@ -0,0 +1,10 @@
+{
+	"position": 3,
+	"label": "Create a block type",
+	"collapsible": true,
+	"collapsed": true,
+	"link": {
+		"type": "generated-index",
+		"title": "Create a block type"
+	}
+}

platform-docs/docs/create-block/attributes.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 4
+---
+
+# Block attributes

platform-docs/docs/create-block/block-supports.md

@@ -0,0 +1,3 @@
+---
+sidebar_position: 3
+---

platform-docs/docs/create-block/first-block-type.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 1
+---
+
+# Your first block type

platform-docs/docs/create-block/nested-blocks.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 5
+---
+
+# Nested blocks

platform-docs/docs/create-block/transforms.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 6
+---
+
+# Block Transforms

platform-docs/docs/create-block/using-styles.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 2
+---
+
+# Using styles and stylesheets

platform-docs/docs/create-block/writing-flow.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 7
+---
+
+# Writing Flow and Pasting