docs: update stacks.js pages (#616)

* docs: update stacks.js pages * fix: update style * chore: remove faulty link * chore: adjust mlc * chore: update mlc * chore: fix mlc --------- Co-authored-by: janniks <[email protected]>
hirosystems · Feb 26, 2024 · 5e6c87c · 5e6c87c
1 parent 67c4122
commit 5e6c87c
Show file tree

Hide file tree

Showing 9 changed files with 78 additions and 67 deletions.
diff --git a/.github/mlc_config.json b/.github/mlc_config.json
@@ -23,6 +23,14 @@
     },
     {
       "pattern": "identity.foundation"
+    },
+    {
+      "pattern": "learn-the-basics",
+      "comment": "// todo: remove once https://github.com/hirosystems/docs/pull/616 is merged"
+    },
+    {
+      "pattern": "stackoverflow.com/questions/tagged/stacks\\-blockchain\\+or\\+clarity\\-lang",
+      "comment": "// Returns a 403 sometimes"
     }
   ],
   "replacementPatterns": [

diff --git a/docs/stacks.js/connect.md → docs/stacks.js/connect.mdx b/docs/stacks.js/connect.md → docs/stacks.js/connect.mdx
@@ -1,6 +1,5 @@
----
-title: Overview
----
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 # Stacks Connect
 
@@ -16,34 +15,45 @@ title: Overview
 </div>
 
 Stacks Connect is a frontend library that allows developers to build Stacks-ready web applications.
-Kickstart your next project with Stacks Connect templates with React, Vue, and more [→ Stacks.js Starters](/stacksjs-starters)
 
-## Features
+What are the main things you can do with Stacks Connect?
 
 - 📸 Prompt a user to sign transactions with their Stacks wallet
 - 🛂 Provide the web-app with the user's Stacks and Bitcoin addresses
 
-## Getting Started with Stacks Connect
+## Start from a template with Stacks Connect included
+
+Get started [from a frontend template](/stacksjs-starters), by running the following command:
+
+```sh
+npm create stacks
+```
 
-- [Add the dependency](#1-add-the-dependency)
-- [Creating `AppConfig` and `UserSession`](#2-creating-appconfig-and-usersession)
-- [Interacting with the wallet](#3-interacting-with-the-wallet)
-  - ["Connect" aka authentication (`showConnect`)](#connect-aka-authentication-showconnect)
-  - [Sending STX (`openSTXTransfer`)](#sending-stx-openstxtransfer)
-  - [Calling Smart-Contracts (`openContractCall`)](#calling-smart-contracts-opencontractcall)
-  - [Sending transactions with post-conditions (`openContractCall`)](#sending-transactions-with-post-conditions-opencontractcall)
-    - [Post-Condition Modes](#post-condition-modes)
+After you have your project set up, you can start using Stacks Connect. Jump ahead to [Interacting with the wallet](#3-interacting-with-the-wallet) to see more code examples.
+
+---
+
+## Manually add Stacks Connect to your project
 
 ### 1. Add the dependency
 
 Add the `@stacks/connect` dependency to your project using your favorite package manager.
-_Some options below_
 
+
+
+<Tabs><TabItem value="npm" label="npm">
 ```sh
 npm install @stacks/connect
+```
+</TabItem><TabItem value="pnpm" label="pnpm">
+```sh
 pnpm install @stacks/connect
+```
+</TabItem><TabItem value="yarn" label="yarn">
+```sh
 yarn add @stacks/connect
 ```
+</TabItem></Tabs>
 
 ### 2. Creating `AppConfig` and `UserSession`
 

diff --git a/docs/stacks.js/faq.md b/docs/stacks.js/faq.md
@@ -4,7 +4,7 @@ sidebar_label: FAQs
 
 # Stacks.js FAQs
 
-#### What are Post Conditions? How do Post Conditions work?
+### What are Post Conditions? How do Post Conditions work?
 
 In computer programming, a post-condition is a condition (or a predicate) that must always be true just after the execution of some section of code or after an operation. And on Stacks, transactions are secured by post-conditions. Thus, if a post-condition check fails on a Clarity smart contract then the entire transaction is reverted.
 
@@ -14,7 +14,7 @@ Post-conditions are less a part of Clarity (the language), but more a part of tr
 Users could send the otherwise-identical transaction (Example: contract-call, executing a function on the blockchain) with OR without different post-conditions, in allow OR deny mode.
 The PCs are managed by the user/wallet/app that's creating the tx; so they are a bit different from the other "safety" features of clarity (Example: asserts, try, https://book.clarity-lang.org/ch06-00-control-flow.html)
 
-#### How to fix the BigInt support when using Stacks.js?
+### How to fix the BigInt support when using Stacks.js?
 
 BigInt support is available in most modern browsers, but some bundlers try to optimize them incorrectly. If you are targeting browsers that are too outdated, building an application with Stacks.js dependencies might fail.
 To solve this set your project `browserslist` to the following [package.json](https://github.com/hirosystems/stacks.js-starters/blob/efb93261b59494f4eb34a7cb5db5d82a84bd3b7c/templates/template-react/package.json#L34-L40).
diff --git a/docs/stacks.js/index.md b/docs/stacks.js/index.md
@@ -1,7 +1,3 @@
----
-sidebar_label: Overview
----
-
 # Stacks.js Overview
 
 <div className="gap-3 flex flex-wrap mb-6">
@@ -32,14 +28,16 @@ It's a collection of various JavaScript libraries allowing developers to interac
 
 <!-- todo: add color -->
 
+## Getting started
+
 <div class="subSections my-8">
   <a href="/stacks.js/connect">
-    <div class="subSectionTitle"><h3>Stacks Connect 🌐</h3><span>→</span></div>
+    <div class="subSectionTitle"><h3>Build a web-app</h3><span>→</span></div>
     <p>Build Stacks-ready web applications</p>
   </a>
   <a href="/stacks.js/getting-started">
-    <div class="subSectionTitle"><h3>Getting Started</h3><span>→</span></div>
-    <p>Explore all that Stacks.js has to offer</p>
+    <div class="subSectionTitle"><h3>Build a service</h3><span>→</span></div>
+    <p>Dive deeper and build on Stacks</p>
   </a>
 </div>
 
@@ -52,7 +50,7 @@ For example, a web app that allows users to interact with the Stacks blockchain
 Most users interact via their favorite Stacks wallet.
 Developers can build web apps, which prompt the user for an action (e.g. sign a transaction), and then the wallet will handle the rest.
 The wallet will act in the security, and best interest of the user, and the user will be able to review the transaction before signing.
-[Read more](./connect.md)
+[Read more](/stacks.js/connect)
 
 ### 🔑 With Private Key Access
 
@@ -63,4 +61,4 @@ Developers can build simple scripts and tools intended for "offline" use.
 Users may use the Stacks.js CLI directly to send a transaction.
 Backends may need to automate signing without direct user interaction.
 In these cases, developers can use the same libraries used by Stacks wallets for account handling and transaction signing.
-[Read more](./installing.md)
+[Read more](/stacks.js/learn-the-basics)
diff --git a/docs/stacks.js/getting-started.md → docs/stacks.js/learn-the-basics.md b/docs/stacks.js/getting-started.md → docs/stacks.js/learn-the-basics.md
@@ -1,12 +1,8 @@
----
-sidebar_label: Getting Started
----
+# Learning the Stacks.js Basics
 
-# Getting Started with Stacks.js
+<div class="bg-neutral-200 rounded-lg text-sm text-neutral-700 p-3">Looking to building Stacks-ready web applications? [Read more on Stacks Connect](/stacks.js/connect)</div>
 
-import StacksjsStartersNote from '../includes/\_stacks.js-starters-note.mdx';
-
-<StacksjsStartersNote/>
+<div class="mb-9"></div>
 
 To introduce the different functionality offered by Stacks.js, we'll walk through a few examples and concepts important to building on the Stacks blockchain.
 
@@ -83,9 +79,6 @@ openSTXTransfer({
 });
 ```
 
-<!-- todo -->
-<!-- [Read more](./connect.md) about transaction signing with Stacks Connect. -->
-
 ### Using a private key 🔑
 
 For full manual transaction signing, we need to provide the sender's private key.

diff --git a/docs/stacks.js/troubleshooting.md b/docs/stacks.js/troubleshooting.md
diff --git a/sidebars/stacks-js.js b/sidebars/stacks-js.js
@@ -25,8 +25,13 @@ module.exports = [
   },
   {
     type: 'doc',
-    label: 'Getting Started',
-    id: 'stacks.js/getting-started',
+    label: 'Learn the basics',
+    id: 'stacks.js/learn-the-basics',
+  },
+  {
+    type: 'doc',
+    label: 'FAQs',
+    id: 'stacks.js/faq',
   },
   {
     type: 'html',
@@ -65,20 +70,4 @@ module.exports = [
     label: 'Integrate Stacking',
     id: 'stacks.js/guides/how-to-integrate-stacking', // TODO: merge both stacking guides
   },
-  {
-    type: 'html',
-    value: 'Other',
-    className: 'section-title',
-    defaultStyle: true,
-  },
-  {
-    type: 'doc',
-    label: 'FAQs',
-    id: 'stacks.js/faq',
-  },
-  {
-    type: 'doc',
-    label: 'Troubleshooting',
-    id: 'stacks.js/troubleshooting',
-  },
 ];
diff --git a/src/css/custom.css b/src/css/custom.css
@@ -20,7 +20,8 @@
 
 @font-face {
   font-family: 'Aeonik Fono';
-  src: url('https://alphaassets.hiro.so/AeonikFono-Regular.woff2') format('woff2'),
+  src:
+    url('https://alphaassets.hiro.so/AeonikFono-Regular.woff2') format('woff2'),
     url('https://alphaassets.hiro.so/AeonikFono-Regular.woff') format('woff');
   font-weight: normal;
   font-style: normal;
@@ -29,7 +30,8 @@
 
 @font-face {
   font-family: 'AeonikMono-Regular';
-  src: url('https://alphaassets.hiro.so/AeonikMono-Regular.woff2') format('woff2'),
+  src:
+    url('https://alphaassets.hiro.so/AeonikMono-Regular.woff2') format('woff2'),
     url('https://alphaassets.hiro.so/AeonikMono-Regular.woff') format('woff');
   font-weight: normal;
   font-style: normal;
@@ -97,6 +99,9 @@
   --ifm-code-font-size: 81.25%;
   --ifm-alert-border-left-width: 0px;
 
+  --ifm-tabs-padding-vertical: 4px;
+  --ifm-tabs-padding-horizontal: 8px;
+
   --aa-primary-color-rgb: var(--ifm-color-primary-lighter);
 }
 
@@ -124,7 +129,10 @@ body {
 }
 
 p {
-  font-family: 'Inter var', system-ui, -apple-system;
+  font-family:
+    'Inter var',
+    system-ui,
+    -apple-system;
 }
 
 [data-theme='dark'] table,
@@ -488,6 +496,15 @@ a.menu__link.menu__link--sublist.menu__link--sublist-caret::after {
   }
 }
 
+/* CODE TABS ================================================================ */
+.tabs-container ul {
+  font-size: small;
+}
+
+.tabs-container .margin-top--md {
+  margin-top: 0 !important;
+}
+
 /* CONTENT MARKDOWN ELEMENTS ================================================ */
 /* Prefixed with `Hiro` */
 
@@ -509,7 +526,7 @@ a.HiroLink {
   font-size: 0.875rem;
   line-height: 1.25rem;
   transition: color 0.15s ease;
-  background-color: ;
+  background-color:;
 }
 
 a.HiroLinkExternal {

diff --git a/vercel.json b/vercel.json
@@ -145,6 +145,11 @@
       "source": "/tutorials/overview",
       "destination": "https://docs.hiro.so/tutorials",
       "permanent": true
+    },
+    {
+      "source": "/stacks.js/getting-started",
+      "destination": "https://docs.hiro.so/stacks.js",
+      "permanent": false
     }
   ]
 }