blockstack
  • About Stacks
  • Developers
  • Apps
  • Community
No Result
View All Result
stacks
No Result
View All Result
Home Stacks Technical

Introducing The Next Generation of Blockstack Documentation

Thomas Osmonson by Thomas Osmonson
September 9, 2020
in Technical

We’re very happy to announce that our docs site has undergone a significant refresh both inside and out! The docs have been updated to use new tooling (Next.js + MDX) and an improved design that meshes with Blockstack’s other properties.

tl:dr

  • Jekyll → Next.js + MDX
  • We implemented Algolia’s Docsearch
  • Updated content and routing for a more intuitive experience
  • Page speed scores went from 60s to upper 90s
  • Standardized styling via @blockstack/ui (our design system)
  • It’s all open-source, check it out!

Why

With much of our efforts going towards our onboarding and Stacks 2.0 work, our docs often felt like a hassle and an afterthought to work on. Our previous docs site used Jekyll and an off-the-shelf theme, which helped us focus on the content while not having to deal with rolling out a bespoke site. However, that made it feel pretty disconnected and out-of-date from all of the improvements we’ve been shipping to some of our other projects, such as our primary website and our new explorer.

We wanted an easy-to-use workflow for editors and contributors, while also making it straightforward and easy to implement new features. At Blockstack, many of our projects use Next.js or React in some way, and as such it was an easy choice to select it for our docs, too. With the introduction of Clarity, Stacks 2.0, and all of the improvements planned for our dev-tooling, we wanted a foundation that would allow us to implement complex and highly interactive features. In addition to our own contributions, these updates allow for community members to make updates as they’re reading. Since the launch of these new docs, we’ve already seen a significant bump in community contributions!

Jekyll vs Next.js + MDX

Jekyll is a standard tool used for many static sites, not just for documentation. It’s easy to use and very reliable, and was a good choice for the docs when we made them originally. But today, we want our docs to be a higher caliber that just isn’t possible with Jekyll. We are planning on rolling our features like direct integration with Connect, our library that app developers can use to integrate with Blockstack. We also want our docs to be highly integrated into Stacks 2.0, and as such want to create components that could allow a user to send a transaction, deploy smart contracts, or even interact with a contract, all directly from the docs.

Next.js allows us to do all of those things and more. Being a framework built on top of React, it allows for static and dynamic applications to be built or rendered on the server, giving advantages such as much better performance, SEO benefits, and allows for us to write complex features that would not be possible in a standard static site.

Markdown can be used with Jekyll, and we’re still using it here in our new site — with major one difference: you can write JSX (templating language used in React) directly inside of the markdown files. This gives us the ability to do some pretty incredible things. Implicitly, this means that when someone writes markdown, we’re using React components to render that content. This can be seen in a few places: the text found within a standard code block in markdown is rendered via a tool called shiki, which under-the-hood uses the same engine that Visual Studio Code uses for their syntax highlighting. We can also do things like line-highlighting, and implement custom languages such as Clarity, our smart contracting language.

Comparison to other docs tooling

There is no shortage of options when it comes to picking a tool for your docs, from something like GitBook, Jekyll, Gatsby, Docz, Nextra, or Docusaurus, there’s probably a tool that fits someone’s needs nearly perfectly. There are a few reasons why we didn’t go with one of these off-the-shelf solutions:

Why not Docusaurus?

The new Docusaurus v2 (alpha) looks like it’s picking up a lot of concepts from the worlds of next.js and Gatsby: server-side rendering, implementing MDX, static site generation, and many modern web-dev practices for performant web pages. This is all great — however it’s a different set of implementations than what we work with at Blockstack. Sure, it’s React and MDX, but we really love next.js here. We use it in many of our projects, and with the recently released features around Incremental Static Generation, it puts itself ahead of most other tools with that alone. Docusaurus also implements a Facebook specific CSS framework called Infima. It’s not easy to theme or modify for your own needs, and as such you’re stuck with something that definitely feels like a Docusaurus site. They have a solution for this called “Swizzling”, however they themselves suggest folks wait to do that until they are in beta.

Why not Gatsby?

Many, many people love Gatsby. Gatsby is a lot like Next.js — it’s a React-based framework for generating static sites. It has made some pretty incredible progress in the space, and they help push everyone forward. They have a robust ecosystem of plugins and tooling support for just about anything you’d want to implement. The way we at Blockstack write components is based off of styled-system, and the person who invented that works at Gatsby. However, GraphQL is the primary tool for data flow within Gatsby — you don’t have to use it, but it’s hard not to. It felt like a few layers of abstraction too much, and when it comes down to it, we have a general preference for next.js with its improvements to static generation, and its ability to be a full-fledged dynamic application — not only a static site.

Okay, but what about Nextra?

Nextra is actually great. It’s a docs system that is built on top of next.js. We only discovered after building out our own docs system in next.js, and looked at a few of their features and integrated some of them with what we had. If you want a next.js docs site that is easy to use and extend, definitely check out nextra!

Better Search

Algolia is world-renowned for their search indexing services, and they have a new and improved offering made specifically for docs sites called Algolia Docsearch. We are using a currently-in-alpha release of their React component that is highly customizable and performs fantastically out of the box, @docsearch/react.

New docs search in action. Pro tip: Hit / on any page to start searching

New design featuring dark mode & better performance

The new docs site features an improved design, and the thing that everyone is actually more interested in: dark mode! The layout and general structure of the site is vastly improved, easier to use, and under-the-hood uses our design system which you can learn more about here.

With the implementation of Next.js, we have put in a lot of effort making the docs site highly performant and accessible. Below you can see a snapshot in performance improvements via Lighthouse Metrics:

Better content structures

As we were working on the new docs site, this gave us the perfect opportunity to quite literally appraise every single page we had, and make edits & improvements as we saw fit. Much of the organization and structure of the site had become disjointed, and during this revamp we changed much of the folder and page structure to be more intuitive and straightforward. This defragmentation of the site map will enable smoother navigation and absorption of material.

What’s next?

With these changes, we can now as a team and community focus on the content and experience of learning how to use Blockstack, Clarity, and all of our tooling. We are currently performing content audits on all of our pages, and in the process of writing out new content for the expected release of Stacks 2.0.

👀 Check out the docs here (source here)
✍️ Learn how to Contribute!

Previous Post

Bounty From Arweave and Blockstack PBC: Clarity on SmartWeave

Next Post

Win Prizes & Crypto: STX Featured As Part of KuCoin’s 3rd Anniversary Celebration

Thomas Osmonson

Thomas Osmonson

A product engineer working to build a user owned internet with Blockstack.

Related Posts

Technical

Build Apps That Sign Transactions with Clarity Smart Contracts on the Stacks 2.0 Testnet

by Mark Hendrickson
July 28, 2020
0

A new version of Blockstack Connect is available for developers who want to build apps that sign transactions with Clarity smart contracts on the Stacks 2.0 Testnet. Now developers can call just a...

Read more
Technical

Upgrade Your App Onboarding Experience With Blockstack Connect

by Mark Hendrickson
June 25, 2020
0

We’re excited to announce the official release of Blockstack Connect, a new JavaScript library that empowers developers to onboard users smoothly into their applications while setting them up for success with contextual...

Read more
Technical

AMA with Diwaker Gupta: Developer Tooling and the Stacks 2.0 Testnet

by Mitchell Cuevas
March 27, 2020
0

Diwaker Gupta, Head of Engineering at Blockstack PBC, recently took to Discord for a virtual AMA. Thank you to those that were able to join and ask questions, the #ask-me-anything channel will...

Read more
Technical

Developer Experience: Q4 2019 Highlights

by Jeff Domke
February 11, 2020
0

It was another eventful and fruitful quarter for the Blockstack ecosystem. As we do quarterly, we recently shared some high-level updates about the ecosystem. In this post, we’ll dive deeper into developer...

Read more

A better internet, built on Bitcoin

Learn About Stacks

Developers

Documentation

Github

Testnet

Papers

Community

Events

Discord

Blog

Forum

Shop

Kakao Talk (한국)

Ecosystem

Discover apps

Stacks Token

Stacks Wallet

Stacks Explorer

Chrome extension

Firefox extension

About

Blockstack PBC

Careers

Roadmap

Patent pledge

Terms & Privacy

Stay up to date

GitHub

Twitter

Discord

Newsletter

This blog will no longer receive new posts and will be available only as an archive. Hiro PBC plans to have a developer-focused blog at hiro.so. Readers looking for Stacks related news and announcements can go to the Stacks ecosystem blog at blog.stacks.co to find updates about the project from various entities and individuals across the decentralized ecosystem.

Hiro PBC (formerly Blockstack PBC) is not registered, licensed, or supervised as a broker-dealer or investment adviser by the Securities and Exchange Commission (SEC), the Financial Industry Regulatory Authority (FINRA), or any other financial regulatory authority or licensed to provide any financial advice or services.

Close
No Result
View All Result
  • Home
  • Home 2
  • Home 3
  • Home 4
  • Home 5
  • Sample Page

Get Started

---
  • Tutorials
  • Install browser
  • Live apps

Technology

---
  • Tutorials
  • Documentation
  • Github
  • White Papers

Community

---
  • Forum
  • Slack
  • Meetup
  • Blog
  • YouTube
  • Videos
  • Signature Fund
  • Telegram (English)
  • Telegram (中文群)

Blockstack

---
  • About
  • What is Blockstack
  • FAQ
  • Roadmap
  • Careers
  • Press
  • Swag
  • Branding
  • Privacy
  • Terms of Use
  • Disclaimers

© 2021 JNews - Premium WordPress news & magazine theme by Jegtheme.

This blog is now an archive. Find technical content here and Stacks news and announcements here.