Skip to content

Latest commit

 

History

History
201 lines (147 loc) · 9.29 KB

README.md

File metadata and controls

201 lines (147 loc) · 9.29 KB
Raw

APItoolkit's Logo APItoolkit's Logo

Marketing Website and Developer Documentation

QuickStatic APItoolkit SDK Join Discord Server APItoolkit Docs

APItoolkit is an end-to-end API and web services management toolkit for engineers and customer support teams. This repository houses our marketing website and developer documentation built using our in-house QuickStatic static site generator.

Table of Contents

Getting Started

The content for every page is written in the Djot markup syntax (Same as Markdown but with some stricter rules) and each page is built using the Shopify liquid templating language and a mix of HTML, CSS, and JavaScript. Everything in the root directory gets copied into the output directory in the exact order it appears, while markdown files are compiled into HTML files.

Setup and Installation

Kindly follow the steps below to run this project locally:

  1. Install QuickStatic using Rust Cargo like so:
cargo install quickstatic
  1. Run the command below to install the styling dependencies:
npm run install
  1. Run the command below to build the site:
npm run serve
  1. Run the command below to build Tailwind CSS:
npm run build

# Or

npm run build:watch

Directories Overview

Kindly click the toggle below to explore the list of important files and directories.

📂 Open Directories Overview
Path Description
_quickstatic/themes QuickStatic themes and components (default and docs).
_quickstatic/public QuickStatic public build.
index The home page.
about The /about page.
assets All image/video assets, fonts, CSS files, JS files, etc.
blog The /blog pages.
compare The /compare page.
contact The /contact page.
docs The /docs pages and content.
events The /events pages.
faq The /faq page.
features The /features pages.
pricing The /pricing page.
privacy-policy The /privacy-policy page.
refund-policy The /refund-policy page.
static Some images and manifest files.
terms-and-conditions The /terms-and-conditions page.
thanks The /thanks page.
tools The /tools pages.
build.sh Script to fetch abd update the latest version of QuickStatic.
Makefile Manage tasks related to Tailwind CSS processing.
quickstatic.yaml QuickStatic configuration options.
tailwind.config.js Tailwind CSS configuration options.

Docs Style Guide

Our documentation is a blooming garden and we will continue to prune and maintain it. Feel free to share your feedback, let us know if something is broken or not working as it ought, and contribute too as we improve things. This style guide document is a WIP and we'll continue to update it. We have some internal guidelines on how things work (we hope to document all of them eventually), however, the sections in the clickable toggle below cover a few important things to note.

📒 Open Docs Style Guide

Style Guide

Everything is written in Markdown/Djot and we have a few custom interactive components (some of which we will improve as time goes on). We're currently adapting the Google Developer Documentation Style Guide and Diátaxis Documentation System, using some principles from both to structure and write our documentation. A few quick writing tips:

  • Create a new pull request for any docs changes (including team members and external contributors), so the docs maintainer can review to ensure everything aligns with existing principles and no inconsistency sneaks in.
  • Follow existing patterns for structure, writing flow, code snippets comments, interactive components, etc. based on the category of docs in context (we currently have the onboarding, SDK guides, dashboard guides, and features pages —with more coming soon) to ensure consistency and sustainable docs.
  • Run your writing through grammar checkers (like Grammarly) to catch typos and other minor issues.
  • Use title case for headings.
  • DO NOT use tabs for code snippets but instead use two spaces.
  • The < and > characters will be omitted by the markdown parser if used in a code snippet, so ensure to replace that with the HTML entity code equivalence (&lt; and &gt;).
  • Indicate omitted code in click-to-copy snippets by using a comment and not an ellipsis points (use comments as much as possible).
  • Always include alt tags in markdown images.
  • Always include the rel="noopener noreferrer" attribute in links that should open in a new tab (e.g., [link text](https://link.com){target="_blank" rel="noopener noreferrer"}).
  • Don't remove or adjust something (styling, configuration, element, image, etc.) if you don't know what it currently does; ask someone first instead (create an issue or ask in Discord).
  • If you make any additions or adjustments to anything, explain it in detail in your pull request.
  • For helpful resources and other general stuff we use, see this awesome technical writing list.

Frontmatter

Here's an example of the frontmatter for the docs pages with the common options used differently in different docs page contexts:

---
title: Home
ogTitle: Sample Home Guide
faLogo: folder-tree
date: 2022-03-23
updatedDate: 2024-05-04
linkTitle: "Documentation"
menuWeight: 20
hideFileTree: true
hideToc: true
pageFullWidth: true
---

Callout Icon Keys

We use Font Awesome icons for our callout component. In the Dashboard Guides, we use only the icon; in the SDK Guides, we use the icon and an accompanying text (e.g., Tip, Warning, etc.).

Format:

<div class="callout">
  <i class="fa-solid fa-forward"></i>
  <p>Content here....</p>
</div>
<div class="callout">
  <p><i class="fa-regular fa-lightbulb"></i> <b>Tip</b></p>
  <p>Content here...</p>
</div>

Icon keys:

Icon Key Description
fa-regular fa-lightbulb Optional information to help a user be more successful.
fa-regular fa-circle-info Highlights information that users should take into account, even when skimming.
fa-solid fa-book Definition of a term.
fa-solid fa-forward Suggested next action (CTA).
fa-solid fa-triangle-exclamation Important warning.

Tab Toggle Component

You can have more than one tab in the tab group toggle component but keep things max at three to ensure a good visual display on most screens. If you want to have multiple tab groups, ensure to increment the data-tab-group value (i.e., group1, group2, etc.) to avoid conflicts. Also, ensure to start all block of code inside a tab content at the beginning of the line instead of nesting it under the <div> element in use; this will avoid extra whitespaces when it is rendered on the site.

<section class="tab-group" data-tab-group="group1">
  <button class="tab-button" data-tab="tab1">Tab A</button>
  <button class="tab-button" data-tab="tab2">Tab B</button>
  <div id="tab1" class="tab-content">Content A</div>
  <div id="tab2" class="tab-content">Content B</div>
</section>

Contributing and Help

To contribute to the development of this project or request help from the community and our team, kindly do any of the following:

License

This repository is published under the MIT license.