From f543289239a8320a298250f7cff9f65ab24b83c2 Mon Sep 17 00:00:00 2001
From: Steve Fenton <99181436+steve-fenton-octopus@users.noreply.github.com>
Date: Thu, 26 Oct 2023 10:28:33 +0100
Subject: [PATCH] Follow up from the docs call

---
 .github/CODEOWNERS |  4 ++
 README.md          | 98 ++++++++++++++++++++++++++++++++++++++++++++++
 src/pages/index.md | 33 +++++++++++++++-
 3 files changed, 133 insertions(+), 2 deletions(-)

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 193d5b8f14..b46f3de144 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -3,6 +3,10 @@
 
 # These owners will be the default owners for everything in the repo. Unless a later match takes precedence,
 
+# Owners of the CODEOWNERS file
+
+/.github/CODEOWNERS @steve-fenton-octopus @tonykelly-octopus
+
 # credits updates get reviewed by michaelnoonan and jburger for open source license compliance
 
 /docs/credits.md @michaelnoonan @jburger
diff --git a/README.md b/README.md
index 353321c259..7bbf72aff2 100644
--- a/README.md
+++ b/README.md
@@ -70,3 +70,101 @@ Before merging to `main` it's possible you'd like to see your changes in a previ
 4. Open `localhost:3000` to view the site, the first page load usually takes a little time
 
 You can generate a static copy of the site using `pnpm build` and run it in a browser with `pnpm preview`.
+
+## Astro hints and tips
+
+### Finding pages to edit
+
+The pages are in the exact page shown on the website, so you can easily translate them. For example:
+
+```
+https://octopus.com/docs/infrastructure/deployment-targets/tentacle
+```
+
+Can be found in the exact same path within `src/pages/`
+
+```
+\docs\src\pages\docs\infrastructure\deployment-targets\tentacle
+```
+
+The file is either in the `tentacle` folder, and named `index.md(x)`, or will be in the parent `deployment-targets` folder and named `tentacle.md`.
+
+The only exception are include files, which are noted below.
+
+### Redirects
+
+No page should ever be deleted! When a page moves or is retired, it should be changed into a redirect file. The redirect ensures users with old links still land on a useful page.
+
+The below shows the complete contents of a redirect page that sends users from:
+
+```
+/docs/administration/authentication/authentication-providers/azure-ad-authentication
+```
+
+To the new location:
+
+```
+/docs/security/authentication/azure-ad-authentication
+```
+
+```
+---
+layout: src/layouts/Redirect.astro
+title: Redirect
+redirect: https://octopus.com/docs/security/authentication/azure-ad-authentication
+pubDate:  2023-01-01
+navSearch: false
+navSitemap: false
+navMenu: false
+---
+```
+
+Having the file kept in place helps future authors as they can easily see where the content has moved. It also prevents a new content item being added that can’t be accessed due to redirects being in place.
+
+Search engines are happy to process meta redirects, just like DNS redirects.
+
+### Include files
+
+Include files let you re-use a chunk of content across many pages. When the information in the shared file changes, all the pages that use it get the update. This can be better than finding all references to a concept, but the trade off is it is more complex to reason.
+
+### Shared content
+
+Shared content is placed in `/src/shared-content/`
+
+You can organize the content in folders within the shared content folder.
+
+#### Referencing shared content
+
+Shared content can be referenced from mdx files. If you have a markdown file and want to reference shared content, follow these steps.
+
+Change the file extension from `.md` to `.mdx`
+
+After the front matter ends with `---` you can import the content:
+
+```javascript
+import DisableDefaultSpace from 'src/shared-content/administration/disable-default-space.include.md'
+```
+
+You can then place the content wherever it needs to be shown:
+
+```html
+<DisableDefaultSpace />
+```
+
+### MDX file differences
+
+When you convert a file from Markdown to MDX, you may encounter some common errors.
+
+#### Headings
+
+The integration for headings allows custom ids to be specified:
+
+```markdown
+## Switching between spaces {#switching-between-spaces}
+```
+
+Within an MDX file, this looks like a code block and will error. Escape the statement with a `\` character:
+
+```markdown
+## Switching between spaces \{#switching-between-spaces}
+```
\ No newline at end of file
diff --git a/src/pages/index.md b/src/pages/index.md
index 0463bc3b5a..76971dc7ad 100644
--- a/src/pages/index.md
+++ b/src/pages/index.md
@@ -17,10 +17,39 @@ This page is not shown on the production site.
 
 - [View the docs site](/docs)
 
-Reports:
+## Reports
 
 - [Missing banners](/report/missing-banner)
 - [Missing metadata](/report/missing-meta)
 - [Missing publication date](/report/missing-pubdate)
 - [Oldest content](/report/oldest-content)
-- [Taxonomy](/report/taxonomy)
\ No newline at end of file
+- [Taxonomy](/report/taxonomy)
+
+## Examples
+
+### Boxes
+
+:::div{.hint}
+This is a hint box
+:::
+
+:::div{.info}
+This is an info box
+:::
+
+:::div{.success}
+This is a success box
+:::
+
+:::div{.warning}
+This is a warning box
+:::
+
+:::div{.problem}
+This is a problem box
+:::
+
+:::div{.info}
+This is an info box
+:::
+