This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch optimize_website in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 9063bd7f4b13b161043cb6e59cf2a867acd217e7 Author: Shawn Yang <[email protected]> AuthorDate: Fri May 22 02:27:58 2026 +0800 Improve docs readability layout --- docs/introduction/overview.md | 86 ---------- src/css/custom.css | 183 ++++++++++++++++++++- .../version-1.0.0/introduction/overview.md | 86 ---------- 3 files changed, 178 insertions(+), 177 deletions(-) diff --git a/docs/introduction/overview.md b/docs/introduction/overview.md index f33d9dd582..d72dbc04ec 100644 --- a/docs/introduction/overview.md +++ b/docs/introduction/overview.md @@ -4,11 +4,6 @@ title: Overview sidebar_position: 1 --- -<div class="themed-logo"> - <img width="65%" alt="Apache Fory logo" src="/img/fory-logo-dark.png" class="themed-logo-dark"/> - <img width="65%" alt="Apache Fory logo" src="/img/fory-logo-light.png" class="themed-logo-light"/> -</div> - **Apache Fory™** is a blazingly-fast multi-language serialization framework for idiomatic domain objects, schema IDL, and cross-language data exchange. @@ -113,84 +108,3 @@ Fory keeps hot paths fast without making every runtime use the same implementati - **Generated and static serializers**: Other runtimes use generated or static serializers where appropriate. - **Zero-copy paths**: Row format and out-of-band buffers avoid unnecessary copies for large values. - **Metadata sharing**: Repeated type information is shared or packed to reduce serialization overhead. - -### Production-Readiness - -Enterprise-grade security and compatibility: - -- **Class Registration**: Whitelist-based deserialization control (enabled by default) -- **Depth Limiting**: Protection against recursive object graph attacks -- **Configurable Policies**: Custom class checkers and deserialization policies -- **Platform Support**: Java 8-24, GraalVM native image, multiple OS platforms - -## Protocols - -Apache Fory™ implements multiple binary protocols optimized for different scenarios: - -| Protocol | Use Case | Key Features | -| ----------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------ | -| **[Xlang Serialization](../specification/xlang_serialization_spec.md)** | Cross-language object exchange | Automatic serialization, references, polymorphism | -| **[Java Serialization](../specification/java_serialization_spec.md)** | High-performance Java-only | Java-native object graphs, JDK hooks, optimized runtime | -| **[Row Format](../specification/row_format_spec.md)** | Analytics and data processing | Zero-copy random access, Arrow compatibility | -| **Python Native** | Python-specific serialization | Pickle/cloudpickle replacement with better performance | - -All protocols share the same optimized codebase, allowing improvements in one protocol to benefit others. - -## Documentation - -### User Guides - -| Guide | Description | Source | Website | -| -------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------- | -| **Java Serialization** | Comprehensive guide for Java serialization | [Java Guide](https://github.com/apache/fory/blob/main/docs/guide/java/) | [View](../guide/java) | -| **Cross-Language Serialization** | Multi-language object exchange | [Xlang Guide](https://github.com/apache/fory/blob/main/docs/guide/xlang/) | [View](../guide/xlang) | -| **Row Format** | Zero-copy random access format | [Java Row Format](https://github.com/apache/fory/blob/main/docs/guide/java/row-format.md) | [View](../guide/java/row-format.md) | -| **Python** | Python-specific features and usage | [Python Guide](https://github.com/apache/fory/blob/main/docs/guide/python/) | [View](../guide/python) | -| **Rust** | Rust implementation and patterns | [Rust Guide](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [View](../guide/rust) | -| **Go** | Go implementation and usage | [Go Guide](https://github.com/apache/fory/blob/main/docs/guide/go/) | [View](../guide/go) | -| **Scala** | Scala integration and best practices | [Scala Guide](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [View](../guide/scala) | -| **GraalVM** | Native image support and AOT compilation | [GraalVM Support](https://github.com/apache/fory/blob/main/docs/guide/java/graalvm-support.md) | [View](../guide/java/graalvm_support) | -| **Development** | Building and contributing to Fory | [Development](https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md) | [View](../community/DEVELOPMENT.md) | - -### Protocol Specifications - -| Specification | Description | Source | Website | -| ----------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -| **Xlang Serialization** | Cross-language binary protocol | [xlang_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_serialization_spec.md) | [View](../specification/xlang_serialization_spec.md) | -| **Java Serialization** | Java-optimized protocol | [java_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/java_serialization_spec.md) | [View](../specification/java_serialization_spec.md) | -| **Row Format** | Row-based binary format | [row_format_spec.md](https://github.com/apache/fory/blob/main/docs/specification/row_format_spec.md) | [View](../specification/row_format_spec.md) | -| **Type Mapping** | Cross-language type conversion | [xlang_type_mapping.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_type_mapping.md) | [View](../specification/xlang_type_mapping.md) | - -## Compatibility - -### Schema Compatibility - -Apache Fory™ supports class schema forward/backward compatibility across **Java, Python, Rust, and Golang**, enabling seamless schema evolution in production systems without requiring coordinated upgrades across all services. Fory provides two schema compatibility modes: - -1. **Schema Consistent Mode (Default)**: Assumes identical class schemas between serialization and deserialization peers. This mode offers minimal serialization overhead, smallest data size, and fastest performance: ideal for stable schemas or controlled environments. - -2. **Compatible Mode**: Supports independent schema evolution with forward and backward compatibility. This mode enables field addition/deletion, limited type evolution, and graceful handling of schema mismatches. Enable using `withCompatibleMode(CompatibleMode.COMPATIBLE)` in Java, `compatible=True` in Python, `compatible_mode(true)` in Rust, or `NewFory(true)` in Go. - -## Community and Support - -### Getting Help - -- **Slack**: Join our [Slack workspace](https://join.slack.com/t/fory-project/shared_invite/zt-36g0qouzm-kcQSvV_dtfbtBKHRwT5gsw) for community discussions -- **Twitter/X**: Follow [@ApacheFory](https://x.com/ApacheFory) for updates and announcements -- **GitHub Issues**: Report bugs and request features at [apache/fory](https://github.com/apache/fory/issues) -- **Mailing Lists**: Subscribe to Apache Fory mailing lists for development discussions - -### Contributing - -We welcome contributions! Please read our [Contributing Guide](https://github.com/apache/fory/blob/main/CONTRIBUTING.md) to get started. - -**Ways to Contribute**: - -- Report bugs and issues -- Propose new features -- Improve documentation -- Submit pull requests -- Add test cases -- Share benchmarks - -See [Development Guide](../community/DEVELOPMENT.md) for build instructions and development workflow. diff --git a/src/css/custom.css b/src/css/custom.css index d5ee709dec..30dec7e27a 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -30,16 +30,27 @@ } .navbar__logo { - height: 2.5rem; + height: 2.25rem; +} + +@media (min-width: 997px) { + .navbar { + padding-left: calc( + var(--fory-doc-sidebar-inset) + + var(--ifm-menu-link-padding-horizontal) + ); + } } .navbar__item { - font-size: 1rem; - margin-right: -10px; + font-size: .95rem; + margin-right: 0; } .navbar__link { - font-size: 1rem; + font-size: .95rem; + padding-left: .55rem; + padding-right: .55rem; } @@ -82,4 +93,166 @@ [data-theme='dark'] .themed-logo-dark { display: block; -} \ No newline at end of file +} + +/* Docs reading surface */ +:root { + --fory-doc-content-width: 860px; + --fory-doc-shell-width: 908px; + --fory-doc-wide-width: 860px; + --fory-doc-gutter-width: 24px; + --fory-doc-sidebar-inset: 2.75rem; + --fory-doc-toc-right-inset: 5.5rem; +} + +.theme-doc-breadcrumbs, +.theme-doc-footer, +.pagination-nav { + max-width: var(--fory-doc-content-width); + margin-left: auto; + margin-right: auto; +} + +.theme-doc-version-badge { + display: inline-block; + margin-left: max(0px, calc((100% - var(--fory-doc-shell-width)) / 2 + var(--fory-doc-gutter-width))); +} + +.theme-doc-markdown { + max-width: var(--fory-doc-shell-width); + margin-left: auto; + margin-right: auto; + font-size: 1.03rem; + line-height: 1.72; +} + +.theme-doc-markdown > * { + max-width: var(--fory-doc-content-width); +} + +.theme-doc-markdown > h1, +.theme-doc-markdown > h2, +.theme-doc-markdown > h3, +.theme-doc-markdown > h4, +.theme-doc-markdown > h5, +.theme-doc-markdown > h6, +.theme-doc-markdown > p, +.theme-doc-markdown > header, +.theme-doc-markdown > ul, +.theme-doc-markdown > ol, +.theme-doc-markdown > blockquote, +.theme-doc-markdown > table, +.theme-doc-markdown > div, +.theme-doc-markdown > pre, +.theme-doc-markdown > .tabs-container, +.theme-doc-markdown > .theme-code-block, +.theme-doc-markdown > .admonition { + margin-left: auto; + margin-right: auto; +} + +.theme-doc-markdown > table { + display: table; +} + +.theme-doc-markdown > pre, +.theme-doc-markdown > table, +.theme-doc-markdown > .tabs-container, +.theme-doc-markdown > .theme-code-block { + max-width: var(--fory-doc-wide-width); +} + +@media (min-width: 997px) { + .theme-doc-breadcrumbs, + .theme-doc-footer, + .pagination-nav, + .theme-doc-markdown { + padding-left: 1.5rem; + padding-right: 1.5rem; + } + + .theme-doc-toc-desktop { + padding-right: var(--fory-doc-toc-right-inset); + } +} + +.theme-doc-markdown h1 { + font-size: 2.6rem; + line-height: 1.1; + margin-bottom: 1.25rem; +} + +.theme-doc-markdown h2 { + font-size: 1.8rem; + margin-top: 3rem; +} + +.theme-doc-markdown h3 { + font-size: 1.35rem; + margin-top: 2.25rem; +} + +.theme-doc-markdown p, +.theme-doc-markdown li { + color: var(--ifm-color-emphasis-800); +} + +.theme-doc-markdown table { + font-size: .95rem; +} + +.theme-doc-markdown th { + background: var(--ifm-color-emphasis-100); +} + +.theme-doc-markdown .theme-code-block, +.theme-doc-markdown pre { + margin-top: 1rem; + margin-bottom: 1.75rem; +} + +.table-of-contents { + font-size: .9rem; + line-height: 1.55; +} + +.table-of-contents__link { + color: var(--ifm-color-emphasis-700); +} + +.table-of-contents__link--active { + color: var(--ifm-color-primary); + font-weight: 600; +} + +.theme-doc-sidebar-container { + background: var(--ifm-background-surface-color); +} + +.theme-doc-sidebar-menu { + padding: .75rem .75rem .75rem var(--fory-doc-sidebar-inset); +} + +.menu__link { + border-radius: 6px; + font-size: .96rem; +} + +.menu__link--active { + font-weight: 600; +} + +.theme-doc-sidebar-menu .menu__caret::before, +.theme-doc-sidebar-menu .menu__link--sublist-caret::after { + background: var(--ifm-menu-link-sublist-icon) 50% / 1rem 1rem no-repeat; + height: .9rem; + min-width: .9rem; + opacity: .72; + width: .9rem; +} + +@media (max-width: 996px) { + .theme-doc-markdown h1 { + font-size: 2.15rem; + } +} diff --git a/versioned_docs/version-1.0.0/introduction/overview.md b/versioned_docs/version-1.0.0/introduction/overview.md index f33d9dd582..d72dbc04ec 100644 --- a/versioned_docs/version-1.0.0/introduction/overview.md +++ b/versioned_docs/version-1.0.0/introduction/overview.md @@ -4,11 +4,6 @@ title: Overview sidebar_position: 1 --- -<div class="themed-logo"> - <img width="65%" alt="Apache Fory logo" src="/img/fory-logo-dark.png" class="themed-logo-dark"/> - <img width="65%" alt="Apache Fory logo" src="/img/fory-logo-light.png" class="themed-logo-light"/> -</div> - **Apache Fory™** is a blazingly-fast multi-language serialization framework for idiomatic domain objects, schema IDL, and cross-language data exchange. @@ -113,84 +108,3 @@ Fory keeps hot paths fast without making every runtime use the same implementati - **Generated and static serializers**: Other runtimes use generated or static serializers where appropriate. - **Zero-copy paths**: Row format and out-of-band buffers avoid unnecessary copies for large values. - **Metadata sharing**: Repeated type information is shared or packed to reduce serialization overhead. - -### Production-Readiness - -Enterprise-grade security and compatibility: - -- **Class Registration**: Whitelist-based deserialization control (enabled by default) -- **Depth Limiting**: Protection against recursive object graph attacks -- **Configurable Policies**: Custom class checkers and deserialization policies -- **Platform Support**: Java 8-24, GraalVM native image, multiple OS platforms - -## Protocols - -Apache Fory™ implements multiple binary protocols optimized for different scenarios: - -| Protocol | Use Case | Key Features | -| ----------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------ | -| **[Xlang Serialization](../specification/xlang_serialization_spec.md)** | Cross-language object exchange | Automatic serialization, references, polymorphism | -| **[Java Serialization](../specification/java_serialization_spec.md)** | High-performance Java-only | Java-native object graphs, JDK hooks, optimized runtime | -| **[Row Format](../specification/row_format_spec.md)** | Analytics and data processing | Zero-copy random access, Arrow compatibility | -| **Python Native** | Python-specific serialization | Pickle/cloudpickle replacement with better performance | - -All protocols share the same optimized codebase, allowing improvements in one protocol to benefit others. - -## Documentation - -### User Guides - -| Guide | Description | Source | Website | -| -------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------- | -| **Java Serialization** | Comprehensive guide for Java serialization | [Java Guide](https://github.com/apache/fory/blob/main/docs/guide/java/) | [View](../guide/java) | -| **Cross-Language Serialization** | Multi-language object exchange | [Xlang Guide](https://github.com/apache/fory/blob/main/docs/guide/xlang/) | [View](../guide/xlang) | -| **Row Format** | Zero-copy random access format | [Java Row Format](https://github.com/apache/fory/blob/main/docs/guide/java/row-format.md) | [View](../guide/java/row-format.md) | -| **Python** | Python-specific features and usage | [Python Guide](https://github.com/apache/fory/blob/main/docs/guide/python/) | [View](../guide/python) | -| **Rust** | Rust implementation and patterns | [Rust Guide](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [View](../guide/rust) | -| **Go** | Go implementation and usage | [Go Guide](https://github.com/apache/fory/blob/main/docs/guide/go/) | [View](../guide/go) | -| **Scala** | Scala integration and best practices | [Scala Guide](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [View](../guide/scala) | -| **GraalVM** | Native image support and AOT compilation | [GraalVM Support](https://github.com/apache/fory/blob/main/docs/guide/java/graalvm-support.md) | [View](../guide/java/graalvm_support) | -| **Development** | Building and contributing to Fory | [Development](https://github.com/apache/fory/blob/main/docs/DEVELOPMENT.md) | [View](../community/DEVELOPMENT.md) | - -### Protocol Specifications - -| Specification | Description | Source | Website | -| ----------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -| **Xlang Serialization** | Cross-language binary protocol | [xlang_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_serialization_spec.md) | [View](../specification/xlang_serialization_spec.md) | -| **Java Serialization** | Java-optimized protocol | [java_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/java_serialization_spec.md) | [View](../specification/java_serialization_spec.md) | -| **Row Format** | Row-based binary format | [row_format_spec.md](https://github.com/apache/fory/blob/main/docs/specification/row_format_spec.md) | [View](../specification/row_format_spec.md) | -| **Type Mapping** | Cross-language type conversion | [xlang_type_mapping.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_type_mapping.md) | [View](../specification/xlang_type_mapping.md) | - -## Compatibility - -### Schema Compatibility - -Apache Fory™ supports class schema forward/backward compatibility across **Java, Python, Rust, and Golang**, enabling seamless schema evolution in production systems without requiring coordinated upgrades across all services. Fory provides two schema compatibility modes: - -1. **Schema Consistent Mode (Default)**: Assumes identical class schemas between serialization and deserialization peers. This mode offers minimal serialization overhead, smallest data size, and fastest performance: ideal for stable schemas or controlled environments. - -2. **Compatible Mode**: Supports independent schema evolution with forward and backward compatibility. This mode enables field addition/deletion, limited type evolution, and graceful handling of schema mismatches. Enable using `withCompatibleMode(CompatibleMode.COMPATIBLE)` in Java, `compatible=True` in Python, `compatible_mode(true)` in Rust, or `NewFory(true)` in Go. - -## Community and Support - -### Getting Help - -- **Slack**: Join our [Slack workspace](https://join.slack.com/t/fory-project/shared_invite/zt-36g0qouzm-kcQSvV_dtfbtBKHRwT5gsw) for community discussions -- **Twitter/X**: Follow [@ApacheFory](https://x.com/ApacheFory) for updates and announcements -- **GitHub Issues**: Report bugs and request features at [apache/fory](https://github.com/apache/fory/issues) -- **Mailing Lists**: Subscribe to Apache Fory mailing lists for development discussions - -### Contributing - -We welcome contributions! Please read our [Contributing Guide](https://github.com/apache/fory/blob/main/CONTRIBUTING.md) to get started. - -**Ways to Contribute**: - -- Report bugs and issues -- Propose new features -- Improve documentation -- Submit pull requests -- Add test cases -- Share benchmarks - -See [Development Guide](../community/DEVELOPMENT.md) for build instructions and development workflow. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
