Skip to content

Commit

Permalink
feat: add table of contents (#795)
Browse files Browse the repository at this point in the history
* feat: add table of contents

Also standardized on in-content H1s away from pagetitles
Fixed missing H2s on gmp overview

Fixes #737

* fix: organize styles and hide TOC on small screens

* fix: only with 3 or more TOC items

* chore: remove dead code
  • Loading branch information
StephenFluin authored Feb 29, 2024
1 parent b46aecd commit 0058f98
Show file tree
Hide file tree
Showing 10 changed files with 160 additions and 66 deletions.
5 changes: 0 additions & 5 deletions src/components/starlight/table-of-contents.astro

This file was deleted.

58 changes: 38 additions & 20 deletions src/layouts/Section.astro
Original file line number Diff line number Diff line change
@@ -1,32 +1,50 @@
---
import MainLayout from "./MainLayout.astro";
import Navigation from "./Navigation.astro";
import TableOfContents from "./TableOfContents.astro";
import { getGithubEditUrl } from '../scripts/github-edit';
import { getGithubEditUrl } from "../scripts/github-edit";
const githubEditUrl = getGithubEditUrl(Astro);
const { title, description, image, hidden } = Astro.props.frontmatter || Astro.props;
const { frontmatter, headings } = Astro.props;
const { description, image, hidden } = Astro.props.frontmatter || Astro.props;
---

<MainLayout {...Astro.props}>
<div id="page">
<div class="sideNav nomobile">
<Navigation />
</div>
<div class="mainBody">
<h1>{title}</h1>
<!-- <div style="display:flex;justify-content:space-between;">
{# <a href="https://github.com/axelarnetwork/documentation/edit/main/{{page.inputPath}}">Suggest Edits</a> #}
</div> -->
<article>
<slot />
<div style="margin-top:32px;"><a href={githubEditUrl}><svg aria-hidden="true" focusable="false" data-prefix="fas" data-icon="pen" class="svg-inline--fa fa-pen fa-w-16 astro-mgbad2nq" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" height="1em" width="1em">
<path fill="currentColor" d="M290.74 93.24l128.02 128.02-277.99 277.99-114.14 12.6C11.35 513.54-1.56 500.62.14 485.34l12.7-114.22 277.9-277.88zm207.2-19.06l-60.11-60.11c-18.75-18.75-49.16-18.75-67.91 0l-56.55 56.55 128.02 128.02 56.55-56.55c18.75-18.76 18.75-49.16 0-67.91z" class="astro-mgbad2nq"></path>
</svg> Edit this page</a></div>
</article>
<div id="page">
<div class="sideNav nomobile">
<Navigation />
</div>
<div class="mainBody">
<article>
<slot />
<div style="margin-top:32px;">
<a href={githubEditUrl}
><svg
aria-hidden="true"
focusable="false"
data-prefix="fas"
data-icon="pen"
class="svg-inline--fa fa-pen fa-w-16 astro-mgbad2nq"
role="img"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 512 512"
height="1em"
width="1em"
>
<path
fill="currentColor"
d="M290.74 93.24l128.02 128.02-277.99 277.99-114.14 12.6C11.35 513.54-1.56 500.62.14 485.34l12.7-114.22 277.9-277.88zm207.2-19.06l-60.11-60.11c-18.75-18.75-49.16-18.75-67.91 0l-56.55 56.55 128.02 128.02 56.55-56.55c18.75-18.76 18.75-49.16 0-67.91z"
class="astro-mgbad2nq"></path>
</svg> Edit this page</a
>
</div>

</article>
{
headings && headings.length > 2 && (
<TableOfContents headings={headings} />
)
}
</div>
</div>
</MainLayout>
36 changes: 36 additions & 0 deletions src/layouts/TableOfContents.astro
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
---
import TableOfContentsHeading from "./TableOfContentsHeading.astro";
const { headings } = Astro.props;
const toc = buildToc(headings);
function buildToc(headings) {
const toc: any[] = [];
const parentHeadings = new Map();
headings.forEach((h) => {
const heading = { ...h, subheadings: [] };
parentHeadings.set(heading.depth, heading);
// Change 2 to 1 if your markdown includes your <h1>
if (heading.depth === 2) {
toc.push(heading);
} else if (heading.depth < 4 && heading.depth > 1) {
if (!parentHeadings.get(heading.depth - 1)) {
console.log("No parent heading for", heading);
return;
}
parentHeadings.get(heading.depth - 1).subheadings.push(heading);
} else {
// Skip headings that are too deep or shallow
}
});
return toc;
}
---

<div id="toc">
<strong>On this page</strong>
<ul>
{toc.map((heading) => <TableOfContentsHeading heading={heading} />)}
</ul>
</div>
18 changes: 18 additions & 0 deletions src/layouts/TableOfContentsHeading.astro
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
const { heading } = Astro.props;
---

<li>
<a href={"#" + heading.slug}>
{heading.text}
</a>
{
heading.subheadings.length > 0 && (
<ul>
{heading.subheadings.map((subheading) => (
<Astro.self heading={subheading} />
))}
</ul>
)
}
</li>
22 changes: 11 additions & 11 deletions src/pages/dev/general-message-passing/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ With GMP, you can:
- The application's executable contract must be deployed on the destination contract.
- The application must be on one of Axelar's supported EVM chains. See [chain names](../reference/mainnet-chain-names) for a list of EVM chains that have an Axelar Gateway deployed. The list is updated as new chains are added.

### Flow architecture (in steps)
## Flow architecture (in steps)
<div class="colored-svg">
<svg
width="100%"
Expand Down Expand Up @@ -537,7 +537,7 @@ With GMP, you can:



### Gateway Interface
## Gateway Interface
In your smart contract, you'll be interacting with the `callContract` or `callContractWithToken` methods of the [gateway contract](https://etherscan.io/address/0x4F4495243837681061C4743b74B3eEdf548D56A5#writeProxyContract).

```solidity
Expand Down Expand Up @@ -565,41 +565,41 @@ function _execute(string calldata sourceChain, string calldata sourceAddress, by



### Steps
## Steps

#### At the source chain
### At the source chain

1. You call a `callContract` (or `callContractWithToken`) function on the Axelar Gateway contract to initiate a call. Once the call is initiated, the user can see its status at https://axelarscan.io/gmp/[txHash] or programmatically track it via the [AxelarJS SDK](/dev/axelarjs-sdk/tx-status-query-recovery#query-transaction-status-by-txhash).
1. You prepay the [gas for the decentralized Axelar consensus](./gas-services/pay-gas) and the necessary transactions to approve and execute on the destination chain.
1. The call enters the Axelar Gateway from the source chain.

#### At the Axelar network
### At the Axelar network

1. The Axelar network confirms the call and utilizes funds from the source chain's native token reserves to cover the gas costs on both the Axelar blockchain and the destination chain.

#### At the destination chain
### At the destination chain

1. The call is approved (Axelar validators come to a consensus by voting, and their votes and signatures are then available to pass to the destination chain), and the approval is relayed to the Axelar Gateway on the destination chain.
1. The executor service relays and executes the approved call to the application's Axelar Executable interface.

Suppose the paid gas (step 2) is insufficient to approve or execute on the destination chain; Axelar offers [monitoring and recovery](/dev/general-message-passing/monitoring) steps to help deal with such scenarios.


### Real-World Breakdown of Cross-Chain [Contract Calls](https://axelarscan.io/gmp/0x93cb0b614b07d6050b164cc3e35da617a2fbefc13069a35369894cac74b861a2:54)
## Real-World Breakdown of Cross-Chain [Contract Calls](https://axelarscan.io/gmp/0x93cb0b614b07d6050b164cc3e35da617a2fbefc13069a35369894cac74b861a2:54)


#### Setup
### Setup

1. The destination application contract implements the `AxelarExecutable.sol` to receive the cross-chain message.

1. The destination application contract stores the address of the local Gateway contract.

#### On Source Chain
### On Source Chain
1. A smart contract on the source chain [calls](https://etherscan.io/tx/0x9b7428e9843c6accee77a9ab19cb374687ed57428968f4ce9591e3378a4da816) `AxelarGateway.callContract()` with the destination chain/address and `payload`, which emits the `ContractCall` event.

1. The smart contract can deposit tokens to the [`AxelarGasService`](https://github.com/axelarnetwork/axelar-cgp-solidity/blob/main/contracts/gas-service/AxelarGasService.sol#L122) contract in the same transaction to pay the Axelar relayers for submitting the intermediate transactions required for cross-chain execution.

#### On Axelar Network
### On Axelar Network

1. A [relayer](https://docs.axelar.dev/learn/network/flow#message-processing-and-relayers) monitors the `ContractCall` event and submits a transaction to the Axelar network to request validation. The relayer also stores the `payload` in a database, keyed by `hash(payload)` for later retrieval.

Expand All @@ -609,7 +609,7 @@ Suppose the paid gas (step 2) is insufficient to approve or execute on the desti

1. A signed [batch](https://axelarscan.io/evm-batches?commandId=0x47d0de91330856d70caecf442341be3faf6e644b83892b214c5a2bcc673ba8ca) of approved payloads is prepared on Axelar that anyone can view.

#### On Destination Chain
### On Destination Chain

1. A relayer [submits](https://bscscan.com/tx/0x72e6c040bfbf26073cdcf55cc4db571badcadd3b9316cf0f53b72f980d3e5100) the signed batch to the destination gateway contract, which records the [approval](https://github.com/axelarnetwork/cgp-spec/blob/main/solidity/contracts/AxelarGateway.sol#L109) of the payload hash and emits a `ContractCallApproved` [event](https://github.com/axelarnetwork/cgp-spec/blob/main/solidity/contracts/AxelarGateway.sol#L144).

Expand Down
4 changes: 1 addition & 3 deletions src/pages/dev/intro.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
---
title: Axelar for Developers
---
# Axelar for Developers

Axelar enables secure token transfers and communication across different blockchains, regardless of consensus mechanisms or message payloads. It’s based on the same [proof-of-stake security model](/learn/security#proof-of-stake-consensus) as many of the chains it connects. Interchain apps built on Axlear are truly permissionless: their transactions cannot be censored by any oracle, relayer, or validator.

Expand Down
15 changes: 8 additions & 7 deletions src/pages/index.astro
Original file line number Diff line number Diff line change
Expand Up @@ -60,13 +60,14 @@ const learnMoreCards = [
];
---

<Section title={title}>
Axelar delivers secure cross-chain communication for Web3, enabling you to
build Interchain dApps that grow beyond a single chain. <em>Secure</em> means
Axelar is built on proof-of-stake, the battle-tested approach used by
Ethereum, Polygon, Cosmos, and more. <em>Cross-chain communication</em> means
you can build a complete experience for your users that lets them interact
with any asset, any application, on any chain with one click.
<Section>
<h1>What is Axelar?</h1>
Axelar delivers secure cross-chain communication for Web3, enabling you to build
Interchain dApps that grow beyond a single chain. <em>Secure</em> means Axelar
is built on proof-of-stake, the battle-tested approach used by Ethereum, Polygon,
Cosmos, and more. <em>Cross-chain communication</em> means you can build a complete
experience for your users that lets them interact with any asset, any application,
on any chain with one click.

<div class="card-grid">
{
Expand Down
10 changes: 2 additions & 8 deletions src/scripts/active.ts
Original file line number Diff line number Diff line change
@@ -1,14 +1,8 @@
// Get the current URL
const currentUrl = window.location.href;
const links = document.querySelectorAll(".sideNav a, nav a");

// Get all links on the page
const links = document.querySelectorAll("a");

// Loop through the links
for (let link of links) {
// If the link's href matches the current URL
if (link.href === currentUrl) {
// Add the active class to the link
link.classList.add("active");
}
}
}
4 changes: 3 additions & 1 deletion src/styles/dark.scss
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,9 @@ html.dark body {
color: $dark-link;
}
.article a,
article a:hover {
article a:hover,
#toc a,
#toc a:hover {
color: $dark-link;
}
a.active,
Expand Down
54 changes: 43 additions & 11 deletions src/styles/main.scss
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
@import url("https://fonts.googleapis.com/css2?family=Space+Grotesk&display=swap");
@import url("https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;700&display=swap");
@import "dark.scss";

$page-width: 1400px;
$font: "Space Grotesk", sans-serif;
$nav-size: 64px;
$text: #1f2937;
$text: rgb(31, 41, 55);
$link-text: rgb(33, 100, 207);

* {
margin: 0;
Expand Down Expand Up @@ -36,8 +37,10 @@ button {
}
}
article a,
article a:hover {
color: rgb(33, 100, 207);
article a:hover,
#toc a,
#toc a:hover {
color: $link-text;
}
h1 {
font-size: 2.25rem;
Expand Down Expand Up @@ -154,6 +157,11 @@ ul li {
.mainBody {
flex: 1;
min-width: 0;
display: flex;
width: calc(100vw - 32px - 300px);
}
article {
overflow-x: hidden;
}
.sideNav {
width: 300px;
Expand Down Expand Up @@ -266,6 +274,24 @@ body pre[class*="language-"] {
div.code-toolbar {
color: white;
}
#toc {
display: block;
position: sticky;
top: 0.5rem;
padding-left: 1rem;
height: fit-content;
font-weight: bold;
ul {
list-style-type: none;
padding-left: 1.2rem;
}
> ul {
width: 300px;
padding-left: 0;
font-weight: normal;
font-size: 14px;
}
}

.callout {
display: flex;
Expand Down Expand Up @@ -432,12 +458,7 @@ astro-island button {
.card span {
color: #1b62d6;
}
@media (max-width: 768px) {
.card-grid {
display: flex;
flex-direction: column;
}
}

.resource-card {
padding: 1rem;
border: 1px solid rgb(229, 231, 235);
Expand Down Expand Up @@ -672,7 +693,18 @@ astro-island button {
display: none;
}

/* Mobile styles */
/* Only render TOC if we have space */
@media (max-width: 950px) {
#toc {
display: none;
}
}
@media (max-width: 768px) {
.card-grid {
display: flex;
flex-direction: column;
}
}
@media (max-width: 650px) {
#page {
padding: 8px;
Expand Down

0 comments on commit 0058f98

Please sign in to comment.