Skip to content

docs: update public guides#2185

Merged
Mirko-von-Leipzig merged 15 commits into
nextfrom
mirko/guides
Jun 3, 2026
Merged

docs: update public guides#2185
Mirko-von-Leipzig merged 15 commits into
nextfrom
mirko/guides

Conversation

@Mirko-von-Leipzig
Copy link
Copy Markdown
Collaborator

@Mirko-von-Leipzig Mirko-von-Leipzig commented Jun 2, 2026

This PR revamps the external/public facing docs to the new distributes sequencer/full node configuration.

I have also:

  • Applied formatting and lints in CI.
  • Moved the above to ci.
  • Changed the doc deployment workflow to only concern itself with that.
  • Renamed a bunch of the make compose-x to make local-network-x
  • Added a spellcheck tool
    • make typos only checks for known typos, not general purpose spellchecking
    • Its npm based :( but I didn't find much else that's easy
    • Currently only targets these markdown files
    • Might expand it to include code in the future but that's overly noisy for this PR

I still need to do the network operator guide. It does contain content, but that was AI generated and has not had a pass (or three) done on it. Please ignore that section.

I would suggest reviewing using the actual docusaurus server, and not as raw markdown nor the diffs since this is effectively a full rewrite. Also note that the guides use a binary/docker tab split.

make install-tools
cd docs/external                                                                                                                                      
npm ci
npm run start:dev

I'll keep pushing changes until the operator guide is complete as well; but this is a large chunk so having reviews come in would be great.

@Mirko-von-Leipzig Mirko-von-Leipzig added the no changelog This PR does not require an entry in the `CHANGELOG.md` file label Jun 2, 2026
@Mirko-von-Leipzig
Copy link
Copy Markdown
Collaborator Author

cc @igamigo who might be interested in the local network setup.

Comment thread docs/external/src/full-node/migrations.md Outdated
Comment thread docs/external/src/index.md Outdated
Copy link
Copy Markdown
Collaborator

@sergerad sergerad left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just typo / nit

Comment thread docs/external/src/local-network-development.md Outdated

## Monitoring and Traces

The local network exports OpenTelemetry traces to Tempo. Grafana is preconfigured with Tempo as a data source, so use
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The local network exports OpenTelemetry traces to Tempo. Grafana is preconfigured with Tempo as a data source, so use
The local network exports OpenTelemetry traces to Tempo. Grafana is pre-configured with Tempo as a data source, so use

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually had to triple check this. Turns out both are correct; your suggestion just means you're old is the old school way 😉

Comment on lines +13 to +30
```text
Clients, wallets, applications
|
Load balancer
|
Public RPC full nodes
|
Block/proof subscriptions
|
Sequencer
/ | \
/ | \
Validator NTX builder Remote batch/block provers
|
Remote tx prover

Network monitor observes RPC, validator, provers, explorer, faucet, and note transport.
```
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Enabling mermaid would allow us to render a much better diagram with a more maintainable representation here:

Suggested change
```text
Clients, wallets, applications
|
Load balancer
|
Public RPC full nodes
|
Block/proof subscriptions
|
Sequencer
/ | \
/ | \
Validator NTX builder Remote batch/block provers
|
Remote tx prover
Network monitor observes RPC, validator, provers, explorer, faucet, and note transport.
```
```mermaid
flowchart TD
A["Clients, wallets, applications"] --> B["Load balancer"]
B --> C["Public RPC full nodes"]
C --> D["Block/proof subscriptions"]
D --> E["Sequencer"]
E --> F["Validator"]
E --> G["NTX builder"]
E --> H["Remote batch/block provers"]
G --> I["Remote tx prover"]
Image

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We've used excalidraw diagrams in the past for these; mermaid is maintainable but so ugly 🥲

I'll see once I get there.

Copy link
Copy Markdown
Contributor

@kkovaacs kkovaacs left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a few nits and a suggestion but otherwise looks good.

@Mirko-von-Leipzig
Copy link
Copy Markdown
Collaborator Author

I'm going to merge this, and then open a new PR for the network operator guide.

Once that's complete, only the internal dev docs need updating but that can wait.

@Mirko-von-Leipzig Mirko-von-Leipzig merged commit 96f53e7 into next Jun 3, 2026
22 checks passed
@Mirko-von-Leipzig Mirko-von-Leipzig deleted the mirko/guides branch June 3, 2026 09:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no changelog This PR does not require an entry in the `CHANGELOG.md` file

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants