Improve docs syntax and formatting (#2267)

Summary:
**Summary**

Reformat the docs in preparation for Docusaurus 2:

- Add syntax highlighting for the code blocks
- Remove `.html` from the Markdown link extensions. Docusaurus 1 allows clean URL but Docusaurus 2 doesn't, so this is necessary
- Wrap API headings in code blocks
- Change the level of some API headings so that they appear in the right table of contents

**Test Plan**

Run Docusaurus website locally and click through.

Try it out - https://draft-js-pc0wv8qnv.now.sh
Pull Request resolved: #2267

Reviewed By: claudiopro

Differential Revision: D18758620

Pulled By: yangshun

fbshipit-source-id: 73b9572e521cbf891abcf5099fec65f0cbef91d2

docs/APIReference-APIMigration.md

@@ -23,7 +23,7 @@ Here is a quick list of what has been changed and how to update your application
 
 **Old Syntax**
 
-```
+```js
 const entityKey = Entity.create(
   urlType,
   'IMMUTABLE',
@@ -33,7 +33,7 @@ const entityKey = Entity.create(
 
 **New Syntax**
 
-```
+```js
 const contentStateWithEntity = contentState.createEntity(
   urlType,
   'IMMUTABLE',
@@ -46,14 +46,14 @@ const entityKey = contentStateWithEntity.getLastCreatedEntityKey();
 
 **Old Syntax**
 
-```
+```js
 const entityInstance = Entity.get(entityKey);
 // entityKey is a string key associated with that entity when it was created
 ```
 
 **New Syntax**
 
-```
+```js
 const entityInstance = contentState.getEntity(entityKey);
 // entityKey is a string key associated with that entity when it was created
 ```
@@ -62,7 +62,7 @@ const entityInstance = contentState.getEntity(entityKey);
 
 **Old Syntax**
 
-```
+```js
 const compositeDecorator = new CompositeDecorator([
   {
     strategy: (contentBlock, callback) => exampleFindTextRange(contentBlock, callback),
@@ -73,7 +73,7 @@ const compositeDecorator = new CompositeDecorator([
 
 **New Syntax**
 
-```
+```js
 const compositeDecorator = new CompositeDecorator([
   {
     strategy: (
@@ -90,7 +90,7 @@ Note that ExampleTokenComponent will receive contentState as a prop.
 
 Why does the 'contentState' get passed into the decorator strategy now? Because we may need it if our strategy is to  find certain entities in the contentBlock:
 
-```
+```js
 const mutableEntityStrategy = function(contentBlock, callback, contentState) {
   contentBlock.findEntityRanges(
     (character) => {
@@ -113,7 +113,7 @@ const mutableEntityStrategy = function(contentBlock, callback, contentState) {
 
 **Old Syntax**
 
-```
+```js
 function findLinkEntities(contentBlock, callback) {
   contentBlock.findEntityRanges(
     (character) => {
@@ -130,7 +130,7 @@ function findLinkEntities(contentBlock, callback) {
 
 **New Syntax**
 
-```
+```js
 function findLinkEntities(contentBlock, callback, contentState) {
   contentBlock.findEntityRanges(
     (character) => {

docs/APIReference-AtomicBlockUtils.md

@@ -11,19 +11,19 @@ parameters and return `EditorState` objects.
 
 ## Static Methods
 
-### insertAtomicBlock
+### `insertAtomicBlock()`
 
-```
+```js
 insertAtomicBlock: function(
   editorState: EditorState,
   entityKey: string,
   character: string
 ): EditorState
 ```
 
-### moveAtomicBlock
+### `moveAtomicBlock()`
 
-```
+```js
 moveAtomicBlock: function(
   editorState: EditorState,
   atomicBlock: ContentBlock,

docs/APIReference-CharacterMetadata.md

@@ -21,7 +21,7 @@ operations are already implemented and available via utility modules. The getter
 methods, however, may come in handy at render time.
 
 See the API reference on
-[ContentBlock](/docs/api-reference-content-block.html#representing-styles-and-entities)
+[ContentBlock](/docs/api-reference-content-block#representing-styles-and-entities)
 for information on how `CharacterMetadata` is used within `ContentBlock`.
 
 ## Overview
@@ -76,11 +76,12 @@ for information on how `CharacterMetadata` is used within `ContentBlock`.
 Under the hood, these methods will utilize pooling to return a matching object,
 or return a new object if none exists.
 
-### create
+### `create()`
 
-```
+```js
 static create(config?: CharacterMetadataConfig): CharacterMetadata
 ```
+
 Generates a `CharacterMetadata` object from the provided configuration. This
 function should be used in lieu of a constructor.
 
@@ -89,29 +90,31 @@ configuration already exists. If so, the pooled object will be returned.
 Otherwise, a new `CharacterMetadata` will be pooled for this configuration,
 and returned.
 
-### applyStyle
+### `applyStyle()`
 
-```
+```js
 static applyStyle(
   record: CharacterMetadata,
   style: string
 ): CharacterMetadata
 ```
+
 Apply an inline style to this `CharacterMetadata`.
 
-### removeStyle
+### `removeStyle()`
 
-```
+```js
 static removeStyle(
   record: CharacterMetadata,
   style: string
 ): CharacterMetadata
 ```
+
 Remove an inline style from this `CharacterMetadata`.
 
-### applyEntity
+### `applyEntity()`
 
-```
+```js
 static applyEntity(
   record: CharacterMetadata,
   entityKey: ?string
@@ -123,26 +126,29 @@ Apply an entity key -- or provide `null` to remove an entity key -- on this
 
 ## Methods
 
-### getStyle
+### `getStyle()`
 
-```
+```js
 getStyle(): DraftInlineStyle
 ```
+
 Returns the `DraftInlineStyle` for this character, an `OrderedSet` of strings
 that represents the inline style to apply for the character at render time.
 
-### hasStyle
+### `hasStyle()`
 
-```
+```js
 hasStyle(style: string): boolean
 ```
+
 Returns whether this character has the specified style.
 
-### getEntity
+### `getEntity()`
 
-```
+```js
 getEntity(): ?string
 ```
+
 Returns the entity key (if any) for this character, as mapped to the global set of
 entities tracked by the [`Entity`](https://github.com/facebook/draft-js/blob/master/src/model/entity/DraftEntity.js)
 module.

docs/APIReference-CompositeDecorator.md

@@ -5,4 +5,4 @@ title: CompositeDecorator
 
 ## Advanced Topic Article
 
-See the [advanced topic article on Decorators](/docs/advanced-topics-decorators.html#compositedecorator).
+See the [advanced topic article on Decorators](/docs/advanced-topics-decorators#compositedecorator).

docs/APIReference-ContentBlock.md

@@ -156,103 +156,101 @@ supplied text.
 
 ## Methods
 
-### getKey()
+### `getKey()`
 
-```
+```js
 getKey(): string
 ```
 Returns the string key for this `ContentBlock`. Block keys are alphanumeric string. It is recommended to use `generateRandomKey` to generate block keys.
 
-### getType()
+### `getType()`
 
-```
+```js
 getType(): DraftBlockType
 ```
 Returns the type for this `ContentBlock`. Type values are largely analogous to
 block-level HTML elements.
 
-### getText()
+### `getText()`
 
-```
+```js
 getText(): string
 ```
 Returns the full plaintext for this `ContentBlock`. This value does not contain
 any styling, decoration, or HTML information.
 
-### getCharacterList()
+### `getCharacterList()`
 
-```
+```js
 getCharacterList(): List<CharacterMetadata>
 ```
-Returns an immutable `List` of `CharacterMetadata` objects, one for each
-character in the `ContentBlock`. (See [CharacterMetadata](/docs/api-reference-character-metadata.html)
-for details.)
+
+Returns an immutable `List` of `CharacterMetadata` objects, one for each character in the `ContentBlock`. (See [CharacterMetadata](/docs/api-reference-character-metadata) for details.)
 
 This `List` contains all styling and entity information for the block.
 
-### getLength()
+### `getLength()`
 
-```
+```js
 getLength(): number
 ```
+
 Returns the length of the plaintext for the `ContentBlock`.
 
-This value uses the standard JavaScript `length` property for the string, and
-is therefore not Unicode-aware -- surrogate pairs will be counted as two
-characters.
+This value uses the standard JavaScript `length` property for the string, and is therefore not Unicode-aware -- surrogate pairs will be counted as two characters.
 
-### getDepth()
+### `getDepth()`
 
-```
+```js
 getDepth(): number
 ```
-Returns the depth value for this block, if any. This is currently used only
-for list items.
+Returns the depth value for this block, if any. This is currently used only for list items.
 
-### getInlineStyleAt()
+### `getInlineStyleAt()`
 
-```
+```js
 getInlineStyleAt(offset: number): DraftInlineStyle
 ```
-Returns the `DraftInlineStyle` value (an `OrderedSet<string>`) at a given offset
-within this `ContentBlock`.
 
-### getEntityAt()
+Returns the `DraftInlineStyle` value (an `OrderedSet<string>`) at a given offset within this `ContentBlock`.
 
-```
+### `getEntityAt()`
+
+```js
 getEntityAt(offset: number): ?string
 ```
-Returns the entity key value (or `null` if none) at a given offset within this
-`ContentBlock`.
 
-### getData()
+Returns the entity key value (or `null` if none) at a given offset within this `ContentBlock`.
 
-```
+### `getData()`
+
+```js
 getData(): Map<any, any>
 ```
+
 Returns block-level metadata.
 
-### findStyleRanges()
+### `findStyleRanges()`
 
-```
+```js
 findStyleRanges(
   filterFn: (value: CharacterMetadata) => boolean,
   callback: (start: number, end: number) => void
 ): void
 ```
-Executes a callback for each contiguous range of styles within this
-`ContentBlock`.
 
-### findEntityRanges()
+Executes a callback for each contiguous range of styles within this `ContentBlock`.
 
-```
+### `findEntityRanges()`
+
+```js
 findEntityRanges(
   filterFn: (value: CharacterMetadata) => boolean,
   callback: (start: number, end: number) => void
 ): void
 ```
-Executes a callback for each contiguous range of entities within this
-`ContentBlock`.
+
+Executes a callback for each contiguous range of entities within this `ContentBlock`.
 
 ## Properties
 
@@ -261,20 +259,26 @@ Executes a callback for each contiguous range of entities within this
 > Use [Immutable Map API](http://facebook.github.io/immutable-js/docs/#/Map)
 > for the `ContentBlock` constructor or to set properties.
 
-### key
+### `key`
+
 See `getKey()`.
 
-### text
+### `text`
+
 See `getText()`.
 
-### type
+### `type`
+
 See `getType()`.
 
-### characterList
+### `characterList`
+
 See `getCharacterList()`.
 
-### depth
+### `depth`
+
 See `getDepth()`.
 
-### data
+### `data`
+
 See `getData()`.