Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

documentation improvements (typos, links, images) #731

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+8 −15
Open

documentation improvements (typos, links, images) #731

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
56dadfa
Update node-networks-sync.mdx
savvar9991 Dec 8, 2024
cc275ea
Update resources.mdx
savvar9991 Dec 8, 2024
0874035
Update ts-sdk.mdx
savvar9991 Dec 8, 2024
785522f
correct typo Update guides.mdx
savvar9991 Dec 8, 2024
b4564d5
Update SEO.mdx
savvar9991 Dec 8, 2024
f10a019
Revert to dynamic image generation
savvar9991 Dec 10, 2024
05b7ded
Merge branch 'main' into update-docs
gregnazario Dec 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion apps/nextra/pages/en/build/guides.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Choose one of the following guides to learn how to use Aptos for your use cases!
</Card>
<Card href="guides/your-first-nft">
<Card.Title>Your First NFT</Card.Title>
<Card.Description>Learn the Aptos Ttoken interface and how to use it to generate your first NFT.</Card.Description>
<Card.Description>Learn the Aptos Token interface and how to use it to generate your first NFT.</Card.Description>
</Card>
<Card href="guides/first-fungible-asset">
<Card.Title>Your First Fungible Asset</Card.Title>
Expand Down
16 changes: 5 additions & 11 deletions apps/nextra/pages/en/build/sdks/ts-sdk.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,33 +6,27 @@ import { RemoteCodeblock, permalinkFetch, Cards, Card } from '@components/index'

export async function getStaticProps() {
return await permalinkFetch([
'https://github.com/aptos-labs/aptos-ts-sdk/blob/bcde1e3af2f09615015c774fb0c2f5206377346e/examples/typescript/simple_transfer.ts#L77-L91'
<a href="https://github.com/aptos-labs/aptos-ts-sdk/blob/bcde1e3af2f09615015c774fb0c2f5206377346e/examples/typescript/simple_transfer.ts#L77-L91">simple_transfer</a>
])
}

# TypeScript SDK

<div className="flex gap-2 mt-6 flex-wrap">
<a target="_blank" href="https://github.com/aptos-labs/aptos-ts-sdk">
![Github Repo Stars](https://img.shields.io/github/stars/aptos-labs/aptos-ts-sdk)
<img src="https://img.shields.io/github/stars/aptos-labs/aptos-ts-sdk" alt="Github Repo Stars" />
</a>
<a target="_blank" href="https://www.npmjs.com/package/@aptos-labs/ts-sdk">
![NPM Version](https://img.shields.io/npm/v/%40aptos-labs%2Fts-sdk)
<img src="https://img.shields.io/npm/v/%40aptos-labs%2Fts-sdk" alt="NPM Version" />
</a>
{/* Revisit later if we need these */}
{/* <a target="_blank" href="https://www.npmjs.com/package/@aptos-labs/ts-sdk">
![Node Version](https://img.shields.io/node/v/%40aptos-labs%2Fts-sdk)
</a> */}
{/* <a target="_blank" href="https://www.npmjs.com/package/@aptos-labs/ts-sdk">
![NPM bundle size](https://img.shields.io/bundlephobia/min/%40aptos-labs/ts-sdk)
</a> */}
<a target="_blank" href="https://aptos-labs.github.io/aptos-ts-sdk/@aptos-labs/ts-sdk-latest">
![Static Badge](https://img.shields.io/badge/SDK_Reference-Docs)
<img src="https://img.shields.io/badge/SDK_Reference-Docs" alt="SDK Reference" />
</a>
Comment on lines 16 to 24
Copy link
Collaborator

Choose a reason for hiding this comment

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

Hmm, these seem to work right now, any reason to change from markdown to HTML?

Copy link
Author

Choose a reason for hiding this comment

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

MDX format is specifically designed to combine the simplicity of Markdown with the power of HTML where needed. In this case, using HTML tags in MDX is a valid and more suitable solution for creating interactive badges
Screenshot before changes:
image
Screenshot after changes:
image
The HTML version provides:

  • Proper handling of external links with target="_blank"
  • Better visual presentation of badges

</div>

The TypeScript SDK allows you to connect, explore, and interact on the Aptos blockchain. You can use it to request data, send transactions, set up test environments, and more!


```bash npm2yarn
npm i @aptos-labs/ts-sdk
```
Expand Down
52 changes: 23 additions & 29 deletions apps/nextra/pages/en/developer-platforms/contribute/setup/SEO.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,36 +8,30 @@ import { docsConfig } from '@docs-config';

# SEO

To simplify Nextra SEO / Open Graph configuration, Aptos Nextra projects use the
`docs.config.js` file for many core Open Graph functionalities.
To simplify Nextra SEO / Open Graph configuration, Aptos Nextra projects use the `docs.config.js` file for many core Open Graph functionalities.

### Dynamic Open Graph Images

The Aptos Docs template takes advantage of [Next.js' dynamic opengraph images](https://vercel.com/docs/functions/og-image-generation)
using the edge runtime to ensure low-latency SEO cards and no cold-starts.
The Aptos Docs template takes advantage of [Next.js' dynamic opengraph images](https://vercel.com/docs/functions/og-image-generation) using the edge runtime to ensure low-latency SEO cards and no cold-starts.

<br />

export function DynamicImage({ title }) {
const imageUrl = `${docsConfig.origin}/api/og.png?title=${encodeURIComponent(title)}`;

return (
<img src={imageUrl} alt="Dynamic Image" />
);
}

<DynamicImage title="Dynamic Image" />
<img
src="https://assets-global.website-files.com/606f63778ec431ec1b930f1f/63dbd502218a274f2a602968_aptos.png"
alt="Example Open Graph Image"
style="width: 100%; max-width: 800px; height: auto; border: 1px solid #eaeaea; border-radius: 8px; margin: 20px 0"
/>
Copy link
Collaborator

Choose a reason for hiding this comment

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

I think this is supposed to be a dynamic image example, so it doesn't make much sense here to change to an img

Copy link
Author

Choose a reason for hiding this comment

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

You're right about this being a dynamic image example. I made these changes because the dynamic image generation wasn't working due to server issues (the server needs to be running with @vercel/og package and proper Edge Runtime setup for OG image generation to work).

I'll create a separate issue to track and fix the server setup required for dynamic image generation. For now, I'll revert these changes to keep the original dynamic image example in the documentation.
image


The Open Graph Images are generated dynamically at runtime from `React` components, and served as a png image.
This is how we are able to include things like the title of the page in the SEO card.

For more details, checkout `/pages/api/og.png.tsx`.
For more details, checkout the file `/pages/api/og.png.tsx`.

<FileTree>
<FileTree.Folder name="pages" defaultOpen>
<FileTree.File name="_meta.ts" />
<FileTree.Folder name="api">
<FileTree.Folder name="og.png.tsx" active />
<FileTree.Folder name="api" defaultOpen>
<FileTree.File name="og.png.tsx" active />
</FileTree.Folder>
<FileTree.Folder name="en" />
<FileTree.File name="_app.tsx" />
Expand All @@ -48,14 +42,14 @@ For more details, checkout `/pages/api/og.png.tsx`.
</FileTree>

> Note: You may be wondering why we use `og.png.tsx` instead of `og.tsx` as the filename.
We use `og.png.tsx` because after testing it extensively, we learned that
Twitter renders opengraph images if their URLs end with the file extension.
> We use `og.png.tsx` because after testing it extensively, we learned that
> Twitter renders opengraph images if their URLs end with the file extension.

### Testing

You can always check the opengraph image by navigating to `/api/og.png`.
You can always check the opengraph image by navigating to `/api/og.png` in your browser.

(e.g., [`http://localhost:3000/api/og.png`](http://localhost:3000/api/og.png))
For example: [`http://localhost:3000/api/og.png`](http://localhost:3000/api/og.png)

### Favicon

Expand All @@ -72,31 +66,31 @@ You can always check the opengraph image by navigating to `/api/og.png`.
</FileTree>

For other assets located in `public/favicon`, you may want to customize the
website icon. You can do so easily by doing the following:

website icon. You can do so easily by following these steps:

<Steps>

##### Generate Favicon
### Generate Favicon

Navigate to [https://favicon.io/favicon-converter/](https://favicon.io/favicon-converter/).
Upload an `svg` file with the logo you'd like to generate your favicon for.

##### Copy assets into `public/favicon`
### Copy assets into `public/favicon`

After generating the assets, favicon.ico should return a zip file containing
After generating the assets, favicon.io will return a zip file containing:

- `android-chrome-192x192.png`
- `favicon.ico`
- ...so on and so forth
- And other favicon assets

Copy all of these and replace the existing files in `public/favicon`
Copy all of these files and replace the existing files in `public/favicon`

##### Deploy
### Deploy
Copy link
Collaborator

Choose a reason for hiding this comment

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

These should be 4 #, as they're part of the favicon section, but I'll accept 3 for now, as it'll match above.

#### Generate Favicon


Deploy your changes to see the new favicon in action.

</Steps>

### Customizing Open Graph

To customize the Open Graph configuration, see `theme.config.tsx`.

2 changes: 1 addition & 1 deletion apps/nextra/pages/en/network/blockchain/node-networks-sync.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ title: "Node Networks and Sync"

Validator nodes and fullnodes form a hierarchical structure with validator nodes at the root and fullnodes everywhere else. The Aptos blockchain distinguishes two types of fullnodes: validator fullnodes and public fullnodes. Validator fullnodes connect directly to validator nodes and offer scalability alongside DDoS mitigation. Public fullnodes connect to validator fullnodes (or other public fullnodes) to gain low-latency access to the Aptos network.

![v-fn-network.svg](/docs/v-fn-network.svg)
![v-fn-network.svg](/apps/nextra/public/docs/v-fn-network.svg)
Copy link
Collaborator

Choose a reason for hiding this comment

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

This image is currently working? I think it should stay how it is

Copy link
Author

Choose a reason for hiding this comment

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

Actually, the image with the original path isn't working - it shows as a broken image. The new path I added points to the correct location of the file in the project structure (/apps/nextra/public/docs/v-fn-network.svg), which makes the image display properly.

Would you like me to show you the difference between how it looks with both paths?
Screenshot before changes:
image
Screenshot after changes:
image


## Node types

Expand Down
2 changes: 1 addition & 1 deletion apps/nextra/pages/en/network/blockchain/resources.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ On Aptos, on-chain state is organized into resources and modules. These are then

## Resources vs Instances

Move modules define struct definitions. Struct definitions may include the abilities such as `key` or `store`. Resources are struct instance with The `key` ability that are stored in global storage or directly in an account. The `store` ability allows struct instances to be stored within resources. An example here is how the APT coin is stored: CoinStore is the resource that contains the APT coin, while the Coin itself is an instance:
Move modules define struct definitions. Struct definitions may include the abilities such as `key` or `store`. Resources are struct instances with the `key` ability that are stored in global storage or directly in an account. The `store` ability allows struct instances to be stored within resources. An example here is how the APT coin is stored: CoinStore is the resource that contains the APT coin, while the Coin itself is an instance:

```move
/// A holder of a specific coin type and associated event handles.
Expand Down
Loading