More updates to documentation

Author: wvbe

README.md

@@ -11,7 +11,16 @@ You could use `docxml` to:
 - Parse content from an existing DOCX file
 - Extract style definitions from a DOTX/DOCX file
 
-### For Deno or for NodeJS
+This documentation for this lib is available at various locations:
+
+[👉 Documentation site](https://wvbe.github.io/docxml)<br />
+[👉 GitHub source](http://github.com/wvbe/docxml)<br />
+[👉 Deno mirror](http://deno.land/x/docxml)<br />
+[👉 npm mirror](http://npmjs.org/package/docxml)
+
+#### For Deno or for NodeJS
+
+[👉 Main article](./docs/setup/deno-or-node.md)
 
 `docxml` can be used in [NodeJS](https://nodejs.org/) and [Deno](https://deno.land) according to the traditions in those
 ecosystems. For Node users, simply `npm install docxml` and then `require()` or `import` as you wish. For Deno users,
@@ -28,9 +37,9 @@ import Docxml, { Paragraph } from 'docxml';
 import Docxml, { Paragraph } from 'https://deno.land/x/docxml/mod.ts';
 ```
 
-[Read all about `docxml` in Deno or Node](./docs/setup/deno-or-node.md)
+#### For JSX or for vanilla
 
-### For JSX or for vanilla
+[👉 Main article](./docs/setup/jsx-or-not.md)
 
 `docxml` is designed to be used in vanilla JavaScript using class component instances, or using JSX if you're on Deno or
 want to use NodeJS and a transpiler like Babel:
@@ -48,11 +57,7 @@ const para = (
 );
 ```
 
-[👉 More on using class components](https://github.com/wvbe/docxml/wiki/Get-started#components)
-
-[👉 More on using JSX](https://github.com/wvbe/docxml/wiki/Get-started#using-jsx)
-
-### For XML or for anything
+#### For XML or for anything
 
 `docxml` is also designed to be used from scratch/entirely programmatically, or using a more ergonomic API
 to transform from an XML document. Both modes work equally well with vanilla JS or JSX.
@@ -75,11 +80,7 @@ await Docx.fromNothing()
 	.toFile('example-2.docx');
 ```
 
-[👉 More on XML rendering rules](https://github.com/wvbe/docxml/wiki/Get-started#rendering-xml)
-
-[👉 Go to the API docs that Deno generates for docxml](https://deno.land/x/docxml@5.2.0/mod.ts)
-
-# Features
+#### Features
 
 To great or small extend, the following features work in the current version of `docxml`. Some items are not ticked off
 yet -- they are not available, but hopefully soon.
@@ -140,7 +141,7 @@ yet -- they are not available, but hopefully soon.
 - [x] Style changes
 - [x] Table row additions and deletions
 
-# Differences with actual MS Word DOCX
+#### Differences with actual MS Word DOCX
 
 Obviously `docxml` is a TypeScript project, which is already very different from how you would normally interact
 with a DOCX document. More meaningfully however, `docxml` is meant to make writing DOCX _easier_ than going straight
@@ -159,7 +160,7 @@ to OOXML. For example;
 - Especially in tables and images, a lot of formatting details are automatically applied. In a lot of cases there
   is no API _yet_ to change them.
 
-# For contributors
+#### For contributors
 
 This project uses unit tests and linting for quality control. To lint, both Deno's own linting as well as ESLint are used.
 Please run both of the following commands to ensure that a GitHub Action does not fail later.

docs/examples/bookmarks.md

@@ -1,6 +1,8 @@
 To cross-reference other parts of the document you need to use the `<Hyperlink>` component, and point it to either an `anchor` or a `bookmark`.
 
-### Reference specific content through bookmarks
+[👉 Read more about hyperlinking external content instead](hyperlinks.md)
+
+### Bookmark ranges
 
 For referencing specific content, you'll need to create a custom bookmark;
 
@@ -52,3 +54,12 @@ docx.toFile('hyperlinks.docx');
 There are a few anchors pre-defined:
 
 - `"_top"`
+- More???
+
+These anchor(s) can be referenced with the `anchor` prop:
+
+```tsx
+<Hyperlink anchor="_top">
+	<Text>Go to top</Text>
+</Hyperlink>
+```

docs/examples/hyperlinks.md

@@ -7,3 +7,5 @@ The `<Hyperlink>` component can be used to create clickable references to extern
 	</Text>
 </Hyperlink>
 ```
+
+[👉 Read more about cross-referencing to another part of the document](bookmarks.md)

docs/examples/paragraphs.md

@@ -0,0 +1,31 @@
+Paragraphs are the bread and butter of text processors like MS Word and Google Docs. Paragraphs are
+the most common top-level building block of an OOXML/DOCX document.
+
+For example, headings and list items are both paragraphs, but with different style properties.
+
+[👉 Read more about styling paragraphs as lists and list items](./lists.md)
+
+You'll probably use the `Paragraph` component all over the place, and get acquinted with its
+formatting options.
+
+```tsx
+<Paragraph
+	alignment="center"
+	spacing={{
+		before: cm(1),
+		after: cm(1),
+	}}
+	indentation={{
+		firstLine: cm(2),
+	}}
+	shading={{
+		background: 'yellow',
+		foreground: 'orange',
+		pattern: 'diagStripe',
+	}}
+>
+	…
+</Paragraph>
+```
+
+[👉 Jump to the type definition of paragraph properties](https://github.com/wvbe/docxml/blob/develop/src/properties/paragraph-properties.ts#L20)

docs/setup/instantiation.md

@@ -0,0 +1,41 @@
+### Starting from nothing
+
+To create a document from _nothing_ is the most straight-forward way to use `docxml`. This creates
+a new document entirely devoid of content, styles, relationships, headers/footers, bookmarks and so
+on.
+
+```tsx
+/** @jsx Docx.jsx */
+import Docx, { Paragraph, Text } from 'docxml';
+
+const docx = Docx.fromNothing();
+```
+
+Or, if you already know what should go in your document;
+
+```tsx
+const docx = Docx.fromJsx(<Paragraph>Hello world!</Paragraph>);
+```
+
+The `docx` instance from the example above provides access to some interesting helper classes that
+are roughly organised in the way that a DOCX archive is itself;
+
+- `docx.bookmarks` to add bookmarks that can be shared between ranges and links. [Read more about cross-referencing to bookmarks](../examples/bookmarks.md).
+- `docx.document` to control the document contents, and relationships directly to `word/document.xml`
+  - `docx.document.styles` to read/write custom style definitions
+  - `docx.document.numbering` to read/write list numbering schemes. [Read more about creating lists and numbering](../examples/lists.md).
+  - `docx.document.settings` to read or write `settings.xml`
+  - `docx.document.headers` and `docx.document.headers` to add those things. [Read more about setting page headers and footers](../examples/headers-and-footers.md).
+
+### Starting from a file
+
+For all intents and purposes a `.dotx` template file is the same as the `.docx` document instance. You can instantiate
+`docxml` from them:
+
+```tsx
+const docx = Docx.fromArchive('my-template.dotx');
+```
+
+The `docx` instance that returns can be used in all the same ways as if you were to instantiate `docxml` in another way,
+but it'll be prepopulated with all the styles, numberings, headers/footers, settings, document contents, etc. that already
+were in your file.

docs/site/_sidebar.md

@@ -1,13 +1,14 @@
+- [Introduction](/)
 - **Setup**
-
   - [Deno, or Node](../setup/deno-or-node.md)
   - [JSX, or not](../setup/jsx-or-not.md)
-
+  - [Instantiation](../setup/instantiation.md)
 - **Examples**
-  - [Tables](../examples/tables.md)
-  - [Images](../examples/images.md)
+  - [Paragraphs](../examples/paragraphs.md)
   - [Lists](../examples/lists.md)
-  - [Sections](../examples/sections.md)
-  - [Headers/footers](../examples/headers-and-footers.md)
   - [Hyperlinks](../examples/hyperlinks.md)
   - [Bookmarks](../examples/bookmarks.md)
+  - [Images](../examples/images.md)
+  - [Tables](../examples/tables.md)
+  - [Sections](../examples/sections.md)
+  - [Headers/footers](../examples/headers-and-footers.md)

index.html

@@ -41,7 +41,7 @@
 				nativeEmoji: true,
 				relativePath: true,
 				maxLevel: 4,
-				subMaxLevel: 2,
+				subMaxLevel: 3,
 				name: 'docxml',
 				nameLink: {
 					'/': '#/',