Reorganize the miscellaneous section

[tsandall]

The MISCELLANEOUS top-level section in the docs navigation has grown organically over time. It feels like it's time to reorganize the content under MISCELLANEOUS that it's easier for people to find and more consistent.

Here's my proposal for where the content ought to live:

CORE

• Policy Language
  • Metadata (currently called "Annotations")
  • Schema (currently called "Type Checking")
  • Future (w/ explanation of opt-in mechanism)
  • Strict Mode (currently called "Compiler Strict Mode")
• External Data
  • Option 1: JWT Tokens
  • OAuth2 and OIDC Samples (currently called "OAuth2 and OIDC")
• Intermediate Representation
• WebAssembly

OPERATIONS

• Storage
  • Disk (should also mention this under Policy Performance page when discussing memory footprint)

MISCELLANEOUS

• Editor and IDE Support
• Comparison to Other Systems

SUPPORT

• FAQ
• Ecosystem
• Enterprise

The only item that I've left out is the Rego Playground link. I think we should make this more prominent--e.g., put a link into the horizontal navbar at the top.

[avinashdesireddy]

/assign

[aarushisoni]

Hi! I want to work on this issue.

[srenatus]

@aarushisoni Please do! Also please have a look at the prior attempts ☝️

[aarushisoni]

@aarushisoni Please do! Also please have a look at the prior attempts ☝️

it will be helpful if you can tell me where exactly I have to make changes like in which file.

[srenatus]

So we're using Hugo for organizing our docs pages. The preamble of each markdown file determines its section, like, wasm.md:

---
title: WebAssembly
kind: misc
weight: 1
---

# What is WebAssembly (Wasm)?

I'm afraid I'm not 100% certain what "weight" means here...

[Parsifal-M]

Hey Team :wave:, @srenatus, @aarushisoni

I hope this helps with the weight :point_right: https://bwaycer.github.io/hugo_tutorial.hugo/content/ordering/

Its something to do with the way Hugo orders content

[charlieegan3]

I once worked on a Hugo site that made use of the weight field on staff pages - it raised the eyebrows of a few new joiners! 😂 In the end I opted for a random order (on build) to avoid the problem of ranking the staff page...

[ashutosh-narkar]

Thanks @lakhanjindam. Go for it! Let us know if you have any questions.

[ashutosh-narkar]

Just confirming, this is the final format we are expecting, right ? https://github.com/open-policy-agent/opa/issues/4614#issue-1213291154

Yes that seems about right.

[ashutosh-narkar]

I haven't tried to build the site locally lately. You can push your changes to your fork and create a draft PR. In that Netlify will generate a docs preview.

[Parsifal-M]

Documentation for setting up docs locally using netlify is kind of outdated, can you share what are the current steps or commands around that ? Also i am getting an error when i try to build site from main branch on netlify

Hey 👋

Apologies, not trying to derail the conversation but I was wondering if you are following this? -> https://www.openpolicyagent.org/docs/latest/contrib-docs/#test-your-changes

I have worked on the docs recently and did not face any issues, maybe also @charlieegan3 might know whats happening here 🤔

[ashutosh-narkar]

I was suggesting you create a draft PR in https://github.com/open-policy-agent/opa with your changes and then you can get the Netlify preview of the docs.

[ashutosh-narkar]

Resource Utilization would be a good place to mention this.