Migrate the Monkey365 documentation site from Material for MkDocs to Zensical

未关闭
  • 哪里不对？
#184 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
30/100
Issue 类型
文档
描述清晰度
需要澄清
活跃度
冷清
领域
documentation

调研方向

Start with the current Monkey365 documentation site and the linked Zensical reference, then inspect the repository's existing documentation configuration and navigation. Done means the site runs on Zensical, its structure is redesigned, and the proposed architecture, collector, rule, ruleset, and contributor topics are documented with build and link validation.

由索引模型根据 Issue 内容生成。

描述

documentation enhancement epic priority-medium

Summary

Migrate the Monkey365 documentation site from Material for MkDocs to Zensical and use the migration as an opportunity to redesign and significantly expand the project documentation.

Material for MkDocs is now in maintenance mode, with development focused on Zensical. Although critical fixes and security updates will continue for a limited period, no new features are expected to be added to Material for MkDocs.

Motivation

The current documentation provides a good introduction to installing, configuring, and running Monkey365. However, many of the project's most powerful capabilities and internal concepts are not documented yet.

Migrating the documentation platform would be a good opportunity to:

  • Redesign the documentation structure and navigation.
  • Improve the contributor and authoring experience.
  • Document Monkey365's architecture and internal workflows.
  • Make advanced customisation and extension points easier to understand.
  • Help users and contributors realise the full potential of Monkey365.

Proposed documentation areas

The redesigned documentation could include dedicated sections for the following topics.

Architecture and core internals
  • High-level architecture.
  • Execution lifecycle.
  • Module and component responsibilities.
  • Authentication and connection management.
  • Internal data flow.
  • Error handling, logging, retries, and throttling.
  • Report generation pipeline.
Collectors
  • Collector lifecycle.
  • Collector structure and conventions.
  • Supported data sources.
  • How collectors are discovered and executed.
  • Creating a custom collector.
  • Collector configuration.
  • Collector output contracts.
Collector helpers
  • Available helper functions.
  • Authentication and API request helpers.
  • Pagination and retry helpers.
  • Logging helpers.
  • Error-handling conventions.
  • Performance considerations.
  • Examples of using helpers in custom collectors.
Data normalisation and aggregation
  • Normalised object structure.
  • Provider-specific transformations.
  • Type and property conventions.
  • How normalised and aggregated data is consumed by rules and reports.
Declarative rules
  • Rule schema and supported properties.
  • Rule metadata.
  • Query and condition syntax.
  • Evidence generation.
  • Severity and classification.
  • Creating and validating a custom rule.
  • Complete rule examples.
Rule evaluation
  • Rule discovery and loading.
  • Evaluation lifecycle.
  • How collected data is selected.
  • Query execution.
  • Pass and fail error states.
  • Evidence construction.
  • Debugging rule evaluation.
Rulesets
  • Ruleset structure.
  • Rule selection and grouping.
  • Creating organisation-specific rulesets.
  • Versioning and maintaining rulesets.
  • Sharing reusable rulesets.
Contributor documentation
  • Documentation development environment.
  • Documentation style guide.
  • Contribution workflow.
  • Adding new pages and navigation entries.
  • Link, formatting, and build validation.

References

主要语言
PowerShell
星标
1.4k
派生
144
平均合并
1 天 21 小时
30 天内合并 PR
1

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

silverhack/monkey365 的其他 Issue

查看 silverhack/monkey365 的全部 Issue

相似的 Issue

更多 Documentation Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。