Skip to main content

Tutorial Intro to the Go Sharp's HandBook

⚡️ The HandBook will help you ship a beautiful documentation site in no time.

💸 Building a custom tech stack is expensive. Instead, focus on your content and just write Markdown files.

💥 Ready for more? Use advanced features like versioning, i18n, search and theme customizations.

💅 Our HandBook is based on Docusaurus.

🧐 Docusaurus is a static-site generator. It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features but can be used to create any kind of site (personal website, product, blog, marketing landing pages, etc).

Fast Track ⏱️​

Let's discover the HandBook in less than 5 minutes.

Getting Started​

Get started by running the local site.

What you'll need​

  • Node.js version 14 or above:
    • When installing Node.js, you are recommended to check all checkboxes related to dependencies.

Start your site​

Run the development server:

cd handbook
npm install
npm start

The cd command changes the directory you're working with. In order to work with your created handbook site, you'll need to navigate the terminal there.

The npm run start command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.

Open docs/intro.md (this page) and edit some lines: the site reloads automatically and displays your changes.

Features​

The HandBook is built with high attention to the developer and contributor experience.

  • ⚛️ Built with 💚 and React:

    • Extend and customize with React
    • Gain full control of your site's browsing experience by providing your own React components

  • Pluggable:

    • Bootstrap your site with a basic template, then use advanced features and plugins
    • Open source your plugins to share with the community

  • ✂️ Developer experience:

    • Start writing your docs right now
    • Universal configuration entry point to make it more maintainable by contributors
    • Hot reloading with lightning-fast incremental build on changes
    • Route-based code and data splitting
    • Publish to GitHub Pages, Netlify, Vercel, and other deployment services with ease

Our shared goal—to help your users quickly find what they need and understand your products better. We share our best practices to help you build your docs site right and well.

  • 🎯 SEO friendly:

    • HTML files are statically generated for every possible path.
    • Page-specific SEO to help your users land on your official docs directly relating their problems at hand.

  • 📝 Powered by MDX:

    • Write interactive components via JSX and React embedded in markdown.
    • Share your code in live editors to get your users to love your products on the spot.

  • 🔍 Search: Your full site is searchable.

  • 💾 Document Versioning: Helps you keep documentation in sync with project releases.

  • 🌍 Internationalization (i18n): Translate your site in multiple locales.

  • ⚡️ Lightning-fast. It follows the PRPL Pattern that makes sure your content loads blazing fast.

  • 🦖 Accessible. Attention to accessibility, making your site equally accessible to all users.

Design principles​

  • Little to learn. The HandBook should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk—Minimal API Surface Area.

  • Intuitive. Users will not feel overwhelmed when looking at the project directory of a HandBook project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with.

  • Layered architecture. The separations of concerns between each layer of our stack (content/theming/styling) should be clear—well-abstracted and modular.

  • Sensible defaults. Common and popular performance optimizations and configurations will be done for users but they are given the option to override them.

  • No vendor lock-in. Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain core infrastructures like React Loadable and React Router cannot be swapped because we do default performance optimization on them, but not higher-level ones. Choice of Markdown engines, CSS frameworks, CSS methodology, and other architectures will be entirely up to users.

We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various components of the HandBook with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.