diff --git a/crates/sui-framework/docs/std/internal.md b/crates/sui-framework/docs/std/internal.md index dcbaf7305d95..7bb58ac3c410 100644 --- a/crates/sui-framework/docs/std/internal.md +++ b/crates/sui-framework/docs/std/internal.md @@ -12,8 +12,8 @@ module example::use_permit; public struct MyType { /* ... */ } public fun test_permit() { -let permit = internal::permit(); -/* external_module::call_with_permit(permit); */ + let permit = internal::permit(); + /* external_module::call_with_permit(permit); */ } ``` @@ -25,7 +25,7 @@ To write a function that is guarded by a - - - + fields: + + + + } ``` diff --git a/crates/sui-framework/docs/sui/event.md b/crates/sui-framework/docs/sui/event.md index 348cb7bcf032..51156af225d8 100644 --- a/crates/sui-framework/docs/sui/event.md +++ b/crates/sui-framework/docs/sui/event.md @@ -7,24 +7,24 @@ creates and sends a custom MoveEvent as a part of the effects certificate of the transaction. Every MoveEvent has the following properties: -- sender -- type signature (T) -- event data (the value of T) -- timestamp (local to a node) -- transaction digest + - sender + - type signature (T) + - event data (the value of T) + - timestamp (local to a node) + - transaction digest Example: ``` module my::marketplace { -use sui::event; -/* ... */ -struct ItemPurchased has copy, drop { -item_id: ID, buyer: address -} -entry fun buy(/* .... */) { -/* ... */ -event::emit(ItemPurchased { item_id: ..., buyer: .... }) -} + use sui::event; + /* ... */ + struct ItemPurchased has copy, drop { + item_id: ID, buyer: address + } + entry fun buy(/* .... */) { + /* ... */ + event::emit(ItemPurchased { item_id: ..., buyer: .... }) + } } ``` diff --git a/crates/sui-framework/docs/sui/package.md b/crates/sui-framework/docs/sui/package.md index 9bbf3f326535..3546e5aa59b4 100644 --- a/crates/sui-framework/docs/sui/package.md +++ b/crates/sui-framework/docs/sui/package.md @@ -704,13 +704,13 @@ package. This ticket only authorizes an upgrade to a package that matches this digest. A package's contents are identified by two things: -- modules: [[u8]] a list of the package's module contents -- deps: [[u8; 32]] a list of 32 byte ObjectIDs of the -package's transitive dependencies + - modules: [[u8]] a list of the package's module contents + - deps: [[u8; 32]] a list of 32 byte ObjectIDs of the + package's transitive dependencies A package's digest is calculated as: -sha3_256(sort(modules ++ deps)) + sha3_256(sort(modules ++ deps)) 
public fun ticket_digest(ticket: &sui::package::UpgradeTicket): &vector<u8>
diff --git a/crates/sui-framework/docs/sui/protocol_config.md b/crates/sui-framework/docs/sui/protocol_config.md
index a1ee6f2911a7..a5d3db5fd3e8 100644
--- a/crates/sui-framework/docs/sui/protocol_config.md
+++ b/crates/sui-framework/docs/sui/protocol_config.md
@@ -33,8 +33,8 @@ We should never need to expose this to user packages.
 ### Arguments
 
 * feature_flag_name - The name of the feature flag as bytes (e.g., b"enable_vdf")
-- It is expected to be a valid UTF-8 string
-- The flag should exist in the protocol config
+  - It is expected to be a valid UTF-8 string
+  - The flag should exist in the protocol config
 
 
 
@@ -53,7 +53,7 @@ We should never need to expose this to user packages.
 use sui::protocol_config;
 
 if (protocol_config::is_feature_enabled(b"enable_accumulators")) {
-// Accumulators are available
+    // Accumulators are available
 };
 ```
 
diff --git a/crates/sui-framework/docs/sui_system/staking_pool.md b/crates/sui-framework/docs/sui_system/staking_pool.md
index 72a087181734..efeabbb27ebf 100644
--- a/crates/sui-framework/docs/sui_system/staking_pool.md
+++ b/crates/sui-framework/docs/sui_system/staking_pool.md
@@ -1099,12 +1099,12 @@ Called at epoch boundaries to process the pending stake.
 ## Function `withdraw_rewards`
 
 This function does the following:
-1. Calculates the total amount of SUI (including principal and rewards) that the provided pool tokens represent
-at the current exchange rate.
-2. Using the above number and the given principal_withdraw_amount, calculates the rewards portion of the
-stake we should withdraw.
-3. Withdraws the rewards portion from the rewards pool at the current exchange rate. We only withdraw the rewards
-portion because the principal portion was already taken out of the staker's self custodied StakedSui.
+    1. Calculates the total amount of SUI (including principal and rewards) that the provided pool tokens represent
+       at the current exchange rate.
+    2. Using the above number and the given principal_withdraw_amount, calculates the rewards portion of the
+       stake we should withdraw.
+    3. Withdraws the rewards portion from the rewards pool at the current exchange rate. We only withdraw the rewards
+       portion because the principal portion was already taken out of the staker's self custodied StakedSui.
 
 
 
fun withdraw_rewards(pool: &mut sui_system::staking_pool::StakingPool, principal_withdraw_amount: u64, pool_token_withdraw_amount: u64, epoch: u64): sui::balance::Balance<sui::sui::SUI>
diff --git a/crates/sui-framework/docs/sui_system/storage_fund.md b/crates/sui-framework/docs/sui_system/storage_fund.md
index 600242b25d96..8cb34a9d3af4 100644
--- a/crates/sui-framework/docs/sui_system/storage_fund.md
+++ b/crates/sui-framework/docs/sui_system/storage_fund.md
@@ -56,12 +56,12 @@ title: Module `sui_system::storage_fund`
 
 Struct representing the storage fund, containing two Balances:
 - total_object_storage_rebates has the invariant that it's the sum of storage_rebate of
-all objects currently stored on-chain. To maintain this invariant, the only inflow of this
-balance is storage charges collected from transactions, and the only outflow is storage rebates
-of transactions, including both the portion refunded to the transaction senders as well as
-the non-refundable portion taken out and put into non_refundable_balance.
+   all objects currently stored on-chain. To maintain this invariant, the only inflow of this
+   balance is storage charges collected from transactions, and the only outflow is storage rebates
+   of transactions, including both the portion refunded to the transaction senders as well as
+   the non-refundable portion taken out and put into non_refundable_balance.
 - non_refundable_balance contains any remaining inflow of the storage fund that should not
-be taken out of the fund.
+   be taken out of the fund.
 
 
 
public struct StorageFund has store
diff --git a/crates/sui-framework/docs/sui_system/sui_system.md b/crates/sui-framework/docs/sui_system/sui_system.md
index 5fc1af258c1b..3606c495786c 100644
--- a/crates/sui-framework/docs/sui_system/sui_system.md
+++ b/crates/sui-framework/docs/sui_system/sui_system.md
@@ -15,9 +15,9 @@ To properly upgrade the SuiSystemStateInner type, we need to ship a
 1. Define a new SuiSystemStateInnertype (e.g. SuiSystemStateInnerV2).
 2. Define a data migration function that migrates the old SuiSystemStateInner to the new one (i.e. SuiSystemStateInnerV2).
 3. Replace all uses of SuiSystemStateInner with SuiSystemStateInnerV2 in both sui_system.move and sui_system_state_inner.move,
-with the exception of the sui_system_state_inner::create function, which should always return the genesis type.
+   with the exception of the sui_system_state_inner::create function, which should always return the genesis type.
 4. Inside load_inner_maybe_upgrade function, check the current version in the wrapper, and if it's not the latest version,
-call the data migration function to upgrade the inner object. Make sure to also update the version in the wrapper.
+  call the data migration function to upgrade the inner object. Make sure to also update the version in the wrapper.
 A detailed example can be found in sui/tests/framework_upgrades/mock_sui_systems/shallow_upgrade.
 Along with the Move change, we also need to update the Rust code to support the new type. This includes:
 1. Define a new SuiSystemStateInner struct type that matches the new Move type, and implement the SuiSystemStateTrait.
@@ -32,7 +32,7 @@ To upgrade Validator type, besides everything above, we also need to:
 2. Define a data migration function that migrates the old Validator to the new one (i.e. ValidatorV2).
 3. Replace all uses of Validator with ValidatorV2 except the genesis creation function.
 4. In validator_wrapper::upgrade_to_latest, check the current version in the wrapper, and if it's not the latest version,
-call the data migration function to upgrade it.
+ call the data migration function to upgrade it.
 In Rust, we also need to add a new case in get_validator_from_table.
 Note that it is possible to upgrade SuiSystemStateInner without upgrading Validator, but not the other way around.
 And when we only upgrade SuiSystemStateInner, the version of Validator in the wrapper will not be updated, and hence may become
@@ -1556,7 +1556,7 @@ This function should be called at the end of an epoch, and advances the system t
 It does the following things:
 1. Add storage charge to the storage fund.
 2. Burn the storage rebates from the storage fund. These are already refunded to transaction sender's
-gas coins.
+   gas coins.
 3. Distribute computation charge to validator stake.
 4. Update all validators.
 
diff --git a/crates/sui-framework/docs/sui_system/sui_system_state_inner.md b/crates/sui-framework/docs/sui_system/sui_system_state_inner.md
index 5ff677cbf6b9..313108392dcb 100644
--- a/crates/sui-framework/docs/sui_system/sui_system_state_inner.md
+++ b/crates/sui-framework/docs/sui_system/sui_system_state_inner.md
@@ -2202,7 +2202,7 @@ This function should be called at the end of an epoch, and advances the system t
 It does the following things:
 1. Add storage charge to the storage fund.
 2. Burn the storage rebates from the storage fund. These are already refunded to transaction sender's
-gas coins.
+   gas coins.
 3. Distribute computation charge to validator stake.
 4. Update all validators.
 
diff --git a/crates/sui-framework/docs/sui_system/validator_set.md b/crates/sui-framework/docs/sui_system/validator_set.md
index 746fbda3a356..d1ef466e509f 100644
--- a/crates/sui-framework/docs/sui_system/validator_set.md
+++ b/crates/sui-framework/docs/sui_system/validator_set.md
@@ -1001,9 +1001,9 @@ Aborts in case the staking amount is smaller than MIN_STAKING_THRESHOLD
 Called by sui_system, to withdraw some share of a stake from the validator. The share to withdraw
 is denoted by principal_withdraw_amount. One of two things occurs in this function:
 1. If the staked_sui is staked with an active validator, the request is added to the validator's
-staking pool's pending stake withdraw entries, processed at the end of the epoch.
+   staking pool's pending stake withdraw entries, processed at the end of the epoch.
 2. If the staked_sui was staked with a validator that is no longer active,
-the stake and any rewards corresponding to it will be immediately processed.
+   the stake and any rewards corresponding to it will be immediately processed.
 
 
 
public(package) fun request_withdraw_stake(self: &mut sui_system::validator_set::ValidatorSet, staked_sui: sui_system::staking_pool::StakedSui, ctx: &sui::tx_context::TxContext): sui::balance::Balance<sui::sui::SUI>
@@ -1120,11 +1120,11 @@ the stake and any rewards corresponding to it will be immediately processed.
 
 Update the validator set at the end of epoch.
 It does the following things:
-1. Distribute stake award.
-2. Process pending stake deposits and withdraws for each validator (adjust_stake).
-3. Process pending stake deposits, and withdraws.
-4. Process pending validator application and withdraws.
-5. At the end, we calculate the total stake for the new epoch.
+  1. Distribute stake award.
+  2. Process pending stake deposits and withdraws for each validator (adjust_stake).
+  3. Process pending stake deposits, and withdraws.
+  4. Process pending validator application and withdraws.
+  5. At the end, we calculate the total stake for the new epoch.
 
 
 
public(package) fun advance_epoch(self: &mut sui_system::validator_set::ValidatorSet, computation_reward: &mut sui::balance::Balance<sui::sui::SUI>, storage_fund_reward: &mut sui::balance::Balance<sui::sui::SUI>, validator_report_records: &mut sui::vec_map::VecMap<address, sui::vec_set::VecSet<address>>, reward_slashing_rate: u64, low_stake_grace_period: u64, ctx: &mut sui::tx_context::TxContext)
@@ -1245,9 +1245,9 @@ It does the following things:
 This function does the following:
 - removes validators from at_risk group if their voting power is above the LOW threshold
 - increments the number of epochs a validator has been below the LOW threshold but above the
-VERY LOW threshold
+    VERY LOW threshold
 - removes validators from the active set if they have been below the LOW threshold for more than
-low_stake_grace_period epochs
+    low_stake_grace_period epochs
 - removes validators from the active set immediately if they are below the VERY LOW threshold
 - activates pending validators if they have sufficient voting power
 
diff --git a/external-crates/move/crates/move-docgen-tests/tests/move/code_block_indent/Move.toml b/external-crates/move/crates/move-docgen-tests/tests/move/code_block_indent/Move.toml
new file mode 100644
index 000000000000..764c241f1f21
--- /dev/null
+++ b/external-crates/move/crates/move-docgen-tests/tests/move/code_block_indent/Move.toml
@@ -0,0 +1,9 @@
+[package]
+name = "Test"
+edition = "2024"
+
+[dependencies]
+MoveStdlib = { local = "../../../../move-stdlib/", addr_subst = { "std" = "0x1" } }
+
+[addresses]
+a = "0x42"
diff --git a/external-crates/move/crates/move-docgen-tests/tests/move/code_block_indent/a__m.md@collapsed_sections.snap b/external-crates/move/crates/move-docgen-tests/tests/move/code_block_indent/a__m.md@collapsed_sections.snap
new file mode 100644
index 000000000000..b853f38cc685
--- /dev/null
+++ b/external-crates/move/crates/move-docgen-tests/tests/move/code_block_indent/a__m.md@collapsed_sections.snap
@@ -0,0 +1,78 @@
+---
+source: crates/move-docgen-tests/tests/testsuite.rs
+assertion_line: 74
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: true
+  include_dep_diagrams: false
+  include_call_diagrams: false
+---
+
+
+# Module `a::m`
+
+
+
+
+## Code Block Formatting
+
+
+Indented code inside a fenced block should be preserved:
+
+```
+fun example() {
+    let x = 1;
+    if (x > 0) {
+        let y = x + 1;
+    };
+}
+```
+
+Text after code block with a nested list:
+
+- Item one
+  - Nested item
+
+
+-  [Code Block Formatting](#@Code_Block_Formatting_0)
+-  [Function `with_code_blocks`](#a_m_with_code_blocks)
+
+
+

+
+
+
+
+
+## Function `with_code_blocks`
+
+Function with code block in doc:
+
+```
+let v = vector[1, 2, 3];
+let sum = 0;
+while (!vector::is_empty(&v)) {
+    sum = sum + vector::pop_back(&mut v);
+};
+```
+
+And indented code block:
+
+  ```
+  indented_block();
+  ```
+
+
+
entry fun with_code_blocks()
+

+
+
+
+##### Implementation
+
+
+
entry fun with_code_blocks() { }
+

diff --git a/external-crates/move/crates/move-docgen-tests/tests/move/code_block_indent/a__m.md@default.snap b/external-crates/move/crates/move-docgen-tests/tests/move/code_block_indent/a__m.md@default.snap
new file mode 100644
index 000000000000..cd8d5d1f1f9b
--- /dev/null
+++ b/external-crates/move/crates/move-docgen-tests/tests/move/code_block_indent/a__m.md@default.snap
@@ -0,0 +1,83 @@
+---
+source: crates/move-docgen-tests/tests/testsuite.rs
+assertion_line: 74
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: false
+  include_dep_diagrams: false
+  include_call_diagrams: false
+---
+
+
+# Module `a::m`
+
+
+
+
+## Code Block Formatting
+
+
+Indented code inside a fenced block should be preserved:
+
+```
+fun example() {
+    let x = 1;
+    if (x > 0) {
+        let y = x + 1;
+    };
+}
+```
+
+Text after code block with a nested list:
+
+- Item one
+  - Nested item
+
+
+-  [Code Block Formatting](#@Code_Block_Formatting_0)
+-  [Function `with_code_blocks`](#a_m_with_code_blocks)
+
+
+

+
+
+
+
+
+## Function `with_code_blocks`
+
+Function with code block in doc:
+
+```
+let v = vector[1, 2, 3];
+let sum = 0;
+while (!vector::is_empty(&v)) {
+    sum = sum + vector::pop_back(&mut v);
+};
+```
+
+And indented code block:
+
+  ```
+  indented_block();
+  ```
+
+
+
entry fun with_code_blocks()
+

+
+
+
+

+Implementation
+
+
+
entry fun with_code_blocks() { }
+

+
+
+
+

diff --git a/external-crates/move/crates/move-docgen-tests/tests/move/code_block_indent/sources/m.move b/external-crates/move/crates/move-docgen-tests/tests/move/code_block_indent/sources/m.move
new file mode 100644
index 000000000000..512acf31cb4c
--- /dev/null
+++ b/external-crates/move/crates/move-docgen-tests/tests/move/code_block_indent/sources/m.move
@@ -0,0 +1,38 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/// # Code Block Formatting
+///
+/// Indented code inside a fenced block should be preserved:
+///
+/// ```
+/// fun example() {
+///     let x = 1;
+///     if (x > 0) {
+///         let y = x + 1;
+///     };
+/// }
+/// ```
+///
+/// Text after code block with a nested list:
+///
+/// - Item one
+///   - Nested item
+module a::m {
+    /// Function with code block in doc:
+    ///
+    /// ```
+    /// let v = vector[1, 2, 3];
+    /// let sum = 0;
+    /// while (!vector::is_empty(&v)) {
+    ///     sum = sum + vector::pop_back(&mut v);
+    /// };
+    /// ```
+    ///
+    /// And indented code block:
+    ///
+    ///   ```
+    ///   indented_block();
+    ///   ```
+    entry fun with_code_blocks() { }
+}
diff --git a/external-crates/move/crates/move-docgen-tests/tests/move/nested_lists/Move.toml b/external-crates/move/crates/move-docgen-tests/tests/move/nested_lists/Move.toml
new file mode 100644
index 000000000000..764c241f1f21
--- /dev/null
+++ b/external-crates/move/crates/move-docgen-tests/tests/move/nested_lists/Move.toml
@@ -0,0 +1,9 @@
+[package]
+name = "Test"
+edition = "2024"
+
+[dependencies]
+MoveStdlib = { local = "../../../../move-stdlib/", addr_subst = { "std" = "0x1" } }
+
+[addresses]
+a = "0x42"
diff --git a/external-crates/move/crates/move-docgen-tests/tests/move/nested_lists/a__m.md@collapsed_sections.snap b/external-crates/move/crates/move-docgen-tests/tests/move/nested_lists/a__m.md@collapsed_sections.snap
new file mode 100644
index 000000000000..9681ea7fa9be
--- /dev/null
+++ b/external-crates/move/crates/move-docgen-tests/tests/move/nested_lists/a__m.md@collapsed_sections.snap
@@ -0,0 +1,98 @@
+---
+source: crates/move-docgen-tests/tests/testsuite.rs
+assertion_line: 74
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: true
+  include_dep_diagrams: false
+  include_call_diagrams: false
+---
+
+
+# Module `a::m`
+
+
+
+
+## Nested Bullet Points
+
+
+- Item one
+  - Nested item one-a
+  - Nested item one-b
+    - Deeply nested item one-b-i
+    - Deeply nested item one-b-ii
+  - Nested item one-c
+- Item two
+- Item three
+  - Nested item three-a
+
+
+
+
+## Nested Enumerated Lists
+
+
+1. First item
+   1. Sub-item one
+   2. Sub-item two
+      1. Sub-sub-item one
+      2. Sub-sub-item two
+   3. Sub-item three
+2. Second item
+3. Third item
+   1. Sub-item one
+
+
+
+
+## Mixed Nested Lists
+
+
+1. Ordered item one
+   - Unordered sub-item a
+   - Unordered sub-item b
+     1. Back to ordered
+     2. Still ordered
+2. Ordered item two
+  - Mixed sub-item
+
+
+-  [Nested Bullet Points](#@Nested_Bullet_Points_0)
+-  [Nested Enumerated Lists](#@Nested_Enumerated_Lists_1)
+-  [Mixed Nested Lists](#@Mixed_Nested_Lists_2)
+-  [Function `nested_list_fn`](#a_m_nested_list_fn)
+
+
+

+
+
+
+
+
+## Function `nested_list_fn`
+
+- Top-level bullet
+  - Nested bullet in function doc
+    - Deeply nested bullet
+- Another top-level bullet
+
+1. First step
+   1. Sub-step one
+   2. Sub-step two
+2. Second step
+
+
+
entry fun nested_list_fn()
+

+
+
+
+##### Implementation
+
+
+
entry fun nested_list_fn() { }
+

diff --git a/external-crates/move/crates/move-docgen-tests/tests/move/nested_lists/a__m.md@default.snap b/external-crates/move/crates/move-docgen-tests/tests/move/nested_lists/a__m.md@default.snap
new file mode 100644
index 000000000000..570dd445c943
--- /dev/null
+++ b/external-crates/move/crates/move-docgen-tests/tests/move/nested_lists/a__m.md@default.snap
@@ -0,0 +1,103 @@
+---
+source: crates/move-docgen-tests/tests/testsuite.rs
+assertion_line: 74
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: false
+  include_dep_diagrams: false
+  include_call_diagrams: false
+---
+
+
+# Module `a::m`
+
+
+
+
+## Nested Bullet Points
+
+
+- Item one
+  - Nested item one-a
+  - Nested item one-b
+    - Deeply nested item one-b-i
+    - Deeply nested item one-b-ii
+  - Nested item one-c
+- Item two
+- Item three
+  - Nested item three-a
+
+
+
+
+## Nested Enumerated Lists
+
+
+1. First item
+   1. Sub-item one
+   2. Sub-item two
+      1. Sub-sub-item one
+      2. Sub-sub-item two
+   3. Sub-item three
+2. Second item
+3. Third item
+   1. Sub-item one
+
+
+
+
+## Mixed Nested Lists
+
+
+1. Ordered item one
+   - Unordered sub-item a
+   - Unordered sub-item b
+     1. Back to ordered
+     2. Still ordered
+2. Ordered item two
+  - Mixed sub-item
+
+
+-  [Nested Bullet Points](#@Nested_Bullet_Points_0)
+-  [Nested Enumerated Lists](#@Nested_Enumerated_Lists_1)
+-  [Mixed Nested Lists](#@Mixed_Nested_Lists_2)
+-  [Function `nested_list_fn`](#a_m_nested_list_fn)
+
+
+

+
+
+
+
+
+## Function `nested_list_fn`
+
+- Top-level bullet
+  - Nested bullet in function doc
+    - Deeply nested bullet
+- Another top-level bullet
+
+1. First step
+   1. Sub-step one
+   2. Sub-step two
+2. Second step
+
+
+
entry fun nested_list_fn()
+

+
+
+
+

+Implementation
+
+
+
entry fun nested_list_fn() { }
+

+
+
+
+

diff --git a/external-crates/move/crates/move-docgen-tests/tests/move/nested_lists/sources/m.move b/external-crates/move/crates/move-docgen-tests/tests/move/nested_lists/sources/m.move
new file mode 100644
index 000000000000..359440184fae
--- /dev/null
+++ b/external-crates/move/crates/move-docgen-tests/tests/move/nested_lists/sources/m.move
@@ -0,0 +1,45 @@
+/// # Nested Bullet Points
+///
+/// - Item one
+///   - Nested item one-a
+///   - Nested item one-b
+///     - Deeply nested item one-b-i
+///     - Deeply nested item one-b-ii
+///   - Nested item one-c
+/// - Item two
+/// - Item three
+///   - Nested item three-a
+///
+/// # Nested Enumerated Lists
+///
+/// 1. First item
+///    1. Sub-item one
+///    2. Sub-item two
+///       1. Sub-sub-item one
+///       2. Sub-sub-item two
+///    3. Sub-item three
+/// 2. Second item
+/// 3. Third item
+///    1. Sub-item one
+///
+/// # Mixed Nested Lists
+///
+/// 1. Ordered item one
+///    - Unordered sub-item a
+///    - Unordered sub-item b
+///      1. Back to ordered
+///      2. Still ordered
+/// 2. Ordered item two
+///   - Mixed sub-item
+module a::m {
+    /// - Top-level bullet
+    ///   - Nested bullet in function doc
+    ///     - Deeply nested bullet
+    /// - Another top-level bullet
+    ///
+    /// 1. First step
+    ///    1. Sub-step one
+    ///    2. Sub-step two
+    /// 2. Second step
+    entry fun nested_list_fn() { }
+}
diff --git a/external-crates/move/crates/move-docgen/src/docgen.rs b/external-crates/move/crates/move-docgen/src/docgen.rs
index 3f3edcccea32..0fe8fb10c6d1 100644
--- a/external-crates/move/crates/move-docgen/src/docgen.rs
+++ b/external-crates/move/crates/move-docgen/src/docgen.rs
@@ -1268,10 +1268,26 @@ impl<'env> Docgen<'env> {
         }
     }
 
+    /// Returns the minimum leading whitespace count across all non-empty lines.
+    fn min_indent(text: &str) -> usize {
+        text.lines()
+            .filter(|line| !line.trim().is_empty())
+            .map(|line| line.len() - line.trim_start().len())
+            .min()
+            .unwrap_or(0)
+    }
+
     /// Outputs documentation text.
     fn doc_text_general(&mut self, env: &Model, for_root: bool, text: &str) {
-        for line in self.decorate_text(env, text).lines() {
-            let line = line.trim();
+        let decorated = self.decorate_text(env, text);
+        let min_indent = Self::min_indent(&decorated);
+        for line in decorated.lines() {
+            let line = if line.trim().is_empty() {
+                ""
+            } else {
+                &line[min_indent..]
+            };
+            let line = line.trim_end();
             if line.starts_with('#') {
                 let mut i = 1;
                 while line[i..].starts_with('#') {
diff --git a/external-crates/move/crates/move-stdlib/docs/std/internal.md b/external-crates/move/crates/move-stdlib/docs/std/internal.md
index ec9156e2d98d..b9d462d1b68f 100644
--- a/external-crates/move/crates/move-stdlib/docs/std/internal.md
+++ b/external-crates/move/crates/move-stdlib/docs/std/internal.md
@@ -13,8 +13,8 @@ module example::use_permit;
 public struct MyType { /* ... */ }
 
 public fun test_permit() {
-let permit = internal::permit();
-/* external_module::call_with_permit(permit); */
+   let permit = internal::permit();
+   /* external_module::call_with_permit(permit); */
 }
 ```
 
@@ -26,7 +26,7 @@ To write a function that is guarded by a