Merge pull request #2058 from OctopusDeploy/sf/docs-call-follow-up

Follow up from the docs call

.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

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}
+```

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)
+- [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
+:::
+