Repository navigation
Docs site: structure and the guides still to write #390
Description
Activity
Placement looks right to me:
serving.mdandopenai.mdunder Deployment,evals.mdunder Guides. Fortypescript-sdk.mdI would put it under Guides for now and split it out only if laya-ts picks up more pages.I am not working on any of the six guides separately, so Routing and Questions and answers are free for someone else. The HTTP API guide should wait for #304 and #281 to settle, since between them they add
/drain,/ready,/metrics, the OpenAI routes and the shared-state notes; #387 adds a batch route worth folding in too.Note that #391's file-based nav means the manual bullet I added to
docs/index.mdin #382 will go away on rebase; thedocs/evals.mdpage is all that is needed. Same for the JSON in #389, which the eval gate in #382 will compare against once it lands.Thank you for organising this. #391 has landed, so the site now has the Guides, Deployment, Fine-tuning and Reference sections with the glob fallback. For the pages in flight: the serving layer in #304 is not going ahead, while #281, #382 and #198 have change requests, and each can add its guide once it lands. A staged-rollout guide (see #367) would also fit well under Guides.
Update on the pages in flight: #281 and #382 have the requested changes in now. The OpenAI routes share the same body limits and request limits as
/v1/systemone, and the eval gate readsanswer_confidenceand skips latency in the default comparison. The/readypiece of the closed #304 is #408 now. Soopenai.mdandevals.mdcan go in with their PRs, and staged-rollout under Guides sounds right to me.- added a commit that references this issue
on Sep 24, 2026 - The structure looks good to me. I’ve opened #415 for the staged-adoption guide under Guides, covering shadow observation → incumbent comparison → held-out policy selection → bounded promotion, without adding runtime surface. With #416 and #418 now covering Routing and Questions/answers, I’d avoid duplicating those. The cleanest standalone gap left looks like CLI + MCP. I’d leave the HTTP API guide until #281, #408 and #387 settle, so it can document one stable serving surface rather than track moving PRs. I’d also keep the README as the compact entry point and move deeper material into guides incrementally.…On Thu, 24 Sep 2026 10:43:04 -0700, "Emiliano G.O." ***@***.***> wrote: emiliano-go left a comment [(NandhaKishorM/laya#390)](#390 (comment)) Update on the pages in flight: [#281](#281) and [#382](#382) have the requested changes in now. The OpenAI routes share the same body limits and request limits as /v1/systemone, and the eval gate reads answer_confidence and skips latency in the default comparison. The /ready piece of the closed [#304](#304) is [#408](#408) now. So openai.md and evals.md can go in with their PRs, and staged-rollout under Guides sounds right to me. — Reply to this email directly, [view it on GitHub](#390?email_source=notifications&email_token=CHDJZC3V3WHIKHLAVB2JVA35QVMKRA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKOBRHEYTCNZZGYY2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5819117961), or [unsubscribe](https://github.com/notifications/unsubscribe-auth/CHDJZC5Z6HEUGNOT747DDJL5QVMKRAVCNFSNUABGKJSXA33TNF2G64TZHMYTGNZVGM4DEMRVGM5US43TOVSTWNJVGY4TANRQG42DHILWAI). You are receiving this because you were mentioned.
- I can take the Command line + MCP server guide next. I checked the current `laya` CLI and the built-in MCP surface (#125 / #303 / #189), and I don’t see a competing docs PR for this guide. I’ll keep it docs-only and task-oriented: when to use the CLI vs MCP, the stable commands/tools and configuration, and links out to Routing / Questions rather than duplicating those guides. I’ll refresh main and the #390 ownership state again before opening the PR.…On Thu, 24 Sep 2026 10:43:04 -0700, "Emiliano G.O." ***@***.***> wrote: emiliano-go left a comment [(NandhaKishorM/laya#390)](#390 (comment)) Update on the pages in flight: [#281](#281) and [#382](#382) have the requested changes in now. The OpenAI routes share the same body limits and request limits as /v1/systemone, and the eval gate reads answer_confidence and skips latency in the default comparison. The /ready piece of the closed [#304](#304) is [#408](#408) now. So openai.md and evals.md can go in with their PRs, and staged-rollout under Guides sounds right to me. — Reply to this email directly, [view it on GitHub](#390?email_source=notifications&email_token=CHDJZC3V3WHIKHLAVB2JVA35QVMKRA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKOBRHEYTCNZZGYY2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5819117961), or [unsubscribe](https://github.com/notifications/unsubscribe-auth/CHDJZC5Z6HEUGNOT747DDJL5QVMKRAVCNFSNUABGKJSXA33TNF2G64TZHMYTGNZVGM4DEMRVGM5US43TOVSTWNJVGY4TANRQG42DHILWAI). You are receiving this because you were mentioned.
@maxfield-allison
Can we use mintlify docs for better readability and we can also integrate more options and docs based on programming languages@baninaveen Its up to the group at large but I'll be honest, I really like what I'm seeing. Interested to hear everyone else's input. I feel like we haven't put to much effort into any particular platform yet so if we're going to make a switch, now is a good time. @Bruce-Yii @emiliano-go @NandhaKishorM thoughts on using Mintlify instead of zensical? I'm not married to anything yet. Edit: I do want to look into it more when I'm not about to pass out though; the most important thing in my opinion is sticking with something FOSS.
- Mintlify looks worth considering, especially this early. My main concern would be lock-in. I’d want the docs source to stay repo-owned, and ideally keep a build/export path that doesn’t depend entirely on the hosted service. @NandhaKishorM, do you see FOSS/self-hosting as a hard requirement for the docs stack, or more of a preference? If that boundary is clear, I think trying the current docs tree on Mintlify would tell us pretty quickly whether the UX improvement is worth the switch.…On Thu, 24 Sep 2026 21:09:03 -0700, Maxfield Allison ***@***.***> wrote: maxfield-allison left a comment [(NandhaKishorM/laya#390)](#390 (comment)) ***@***.***(https://github.com/baninaveen) Its up to the group at large but I'll be honest, I really like what I'm seeing. Interested to hear everyone else's input. I feel like we haven't put to much effort into any particular platform yet so if we're going to make a switch, now is a good time. ***@***.***(https://github.com/Bruce-Yii) ***@***.***(https://github.com/emiliano-go) ***@***.***(https://github.com/NandhaKishorM) thoughts on using [Mintlify](https://www.mintlify.com/docs/quickstart) instead of zensical? I'm not married to anything yet. — Reply to this email directly, [view it on GitHub](#390?email_source=notifications&email_token=CHDJZCZFQVFQHFCZ4N5NZGT5QXVV7A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKOBSGY2TGMRZHAYKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5826532980), or [unsubscribe](https://github.com/notifications/unsubscribe-auth/CHDJZC6UPCN6JRLUEJXJ6E35QXVV7AVCNFSNUABGKJSXA33TNF2G64TZHMYTGNZVGM4DEMRVGM5US43TOVSTWNJVGY4TANRQG42DHILWAI). You are receiving this because you were mentioned.Reacted by Maxfield Allison
Zensical is a no brainer for me. Open source, MIT, and lots of support and development. It's the current growing standard as MKDocs falls behind. Also, deploy is super easy, both in GH pages and in Cloudflare pages.
Reacted by Maxfield AllisonIn my opinion, clear and well-structured documentation enables developers to integrate our solutions into their specific use cases more easily. Providing step-by-step guides, practical examples, and integration instructions not only improves the developer experience but also helps AI agents index and understand our documentation, making it easier for them to recommend our solutions and work effectively across different AI agent ecosystems.
@NandhaKishorM Whats your opinion.
If Laya plans to offer paid or cloud-based services in the future, having clear and well-structured documentation will make it much easier for developers to adopt, integrate, and use those services.
I can take the “Benchmarks and known limits” guide (item 6) as a separate docs-only PR. I checked the open PRs and found no
docs/benchmarks*ordocs/limits*page in flight. I’ll ground it in the currentBENCHMARKS.md, README and reproduction scripts, explain how to read the reported numbers and limits, and link to the source tables rather than duplicate changing measurements.Thank you all. The staged adoption guide (#415) and the benchmarks and known limits guide (#480) have landed. The routing guide (#461), the questions and answers guide (#418), the
answer_confidencereference (#419) and the CLI and MCP guide (#430) each have a small change request, mostly about describing confidence as calibrated only after a validated temperature fit. I'll keep this open until those land.I'd like to take the HTTP API guide (item 3). With the recent changes landing — the null score level now 422s, the lone-surrogate 400, the option-cap error — I think a single page describing the /v1/systemone request/response shapes and error behavior is genuinely useful for people porting from Jev. I'll link to the serving and OpenAI pages once #281 settles rather than duplicating them. If anyone's already sitting on this, say the word and I'll stand down.
Started this as #490 — single new page,
docs/http-api.md, no nav or index edits.- added a commit that references this issue
on Sep 25, 2026 After looking into Mintlify more, I'd prefer to stick with Zensical. I like how Mintlify presents the docs, but the MIT license on the starter template doesn't cover the whole platform. The
mintCLI uses Elastic License 2.0, which isn't an open source license. FOSS was the most important thing for me, and I feel like moving the docs onto tooling that isn't open source goes against the ethos of this project.@baninaveen I agree that we need the step-by-step guides and practical examples you're describing. That's what I'd like to keep working toward with this issue. I don't think we need to change platforms to do that, and Zensical lets us keep the build tooling open source too.
@maxfield-allison Okay, could you also explore Starlight? It looks highly customizable and could be a good fit for us. It can also be deployed directly to GitHub Pages
I followed your point about keeping the solution FOSS, but I think we should also consider the overall UX and navigability of Laya’s documentation. Each documentation area should be easy to discover, search, navigate, and understand.
Starlight gives us a strong foundation for this because we can customize the sidebar structure, navigation, search experience, components, styling, and even override parts of the UI when required.
This could help us maintain the FOSS approach while still giving Laya a polished and consistent documentation experience.
@baninaveen starlight is cool and all, but it adds unnecessary complexity for docs. Docs are there to be simple.
Yes, starlight allows each doc to use its own JS, but it isn't a real use case for 99% of doc pages.
Zensical is plain markdown and allows standard html/css/js overrides.
As always, KISS is the best solution. If we ever need to migrate somewhere else, they're both drop-in replacements.
Reacted by Bruce-Yii, Maxfield Allison and Naveen Banisetti
I'm really not seeing the reason or case that demands starlight over zensical at this point.
Reacted by Bruce-Yii and Naveen BanisettiAll that said, I'll be giving starlight a shot on upcoming project releases of my own @baninaveen; I'm never unhappy to learn about alternatives. =]
Reacted by Bruce-Yii and Naveen Banisetti- added 5 commits that reference this issue
on Sep 27, 2026
With the site live, I'd like to agree on its structure before the next batch of pages lands. Open PRs already add guides for serving, OpenAI compatibility, evaluations and the TypeScript SDK: @emiliano-go's #304, #281 and #382, and @baninaveen's #198. @Bruce-Yii's #328, @coder-jeffery's #362 and @PerryLink's #378 also update existing guides. I'd like your input on where those pages belong and what else the docs need.
Structure. The proposed navigation has four sections, ordered through
docs/.nav.yml:A page or folder that isn't listed still shows up under Guides. Contributors can add a page without changing the nav, then place it in another section when needed.
For the pages in open PRs, I'd put
serving.mdandopenai.mdunder Deployment next to Docker, andevals.mdunder Guides. I'm not sure abouttypescript-sdk.md. It could go in Guides, or in a section of its own if laya-ts gets more pages.Guides still to write. These topics could use fuller guides on the site, drawing on the README and the existing examples and references. Each would be a separate PR, with the README summaries kept in place:
Routerpicks a checkpoint,langoverrides, bringing your own language detection, preload and memory, mixed batches, and whatRouteDecisionholds.choice,scoreandnoul, reading probabilities and confidence (including the calibrated confidence from feat(agent): report the calibrated confidence alongside the existing one #126), confidence gating, and the presets.BENCHMARKS.md.Routing and questions and answers look like useful next steps. If you're already working on one of these guides, please say so here so we don't duplicate it.
README. I'm not moving anything out of it. @NandhaKishorM, if you want the README trimmed to summaries that link into these pages later, that can be its own step once the guides exist.
Would you group these differently, or is there a topic missing?