DOCSEARCHbyAlgolia
Submit Docs

AriaDocs Documentation

website·Indexed 31 days ago

https://docs-ruddy-five.vercel.app

A modern, flexible template for building documentation sites using Next.js and server components. Features include a custom Markdown-based component system with support for steppers, tabs, code blocks, and recursive file system views, as well as integration with Algolia DocSearch.

Tokens
5.8K
Snippets
31
Records
37
Agent score
74%

What's inside AriaDocs

  1. Overview of AriaDocs features and capabilities

    AriaDocs is a documentation toolkit and template designed for knowledge bases, project documentation, and blogs. It supports Markdown and MDX for interactive content, nested hierarchical page structures, a dedicated blog section, and SEO optimization. Key technical capabilities include syntax highlighting, code line highlighting with titles, and the ability to embed custom reusable Markdown components via Static Site Generation (SSG).

  2. Understand the Next.js project directory structure

    The project is organized into several key directories to ensure scalability and maintainability:

    • app/: Contains the main Next.js application code, including routing, layouts, and pages for the docs and blog sections.
    • components/: Stores reusable UI elements. It is categorized into subfolders such as ui and markdown (e.g., note.tsx, image.tsx, table.tsx) and general navigation like navbar.tsx.
    • styles/: Contains global and component-specific CSS files, including globals.css, syntax.css, and overrides.css.
    • contents/: Stores Markdown files for the documentation and blog. Files are organized by type (e.g., docs/, tutorials/, blogs/) and use frontmatter for metadata.
    • public/: Holds static assets (images, videos, fonts, icons) accessible via direct URL.
    • lib/: Contains shared helper functions and utilities, such as markdown.ts for parsing and routes-config.ts for routing logic.

  3. Create a code block with line numbers and highlighting

    To create a code block with specific features, use a modified markdown fence syntax. You can provide a filename, enable line numbers using the showLineNumbers keyword, and specify lines to highlight using curly braces {}. For highlighting, use single numbers for individual lines or ranges (e.g., 3-5).
    ```javascript:main.js showLineNumbers {3-4}

function isRocketAboutToCrash() {
    // Check if the rocket is stable
    if (!isStable()) {
        NoCrash(); // Prevent the crash
    }
}

  4. Apply for Algolia DocSearch for open-source projects

    Algolia provides DocSearch for free to open-source projects. To apply, visit the DocSearch Application page and provide your website URL, the CSS selectors for your headings and content, and your GitHub repository link. Upon approval, Algolia will provide the necessary Application ID, Search API Key, and Index Name required for integration.

  5. Install AriaDocs by cloning the GitHub repository

    To set up AriaDocs manually, clone the official repository, install dependencies using npm, and start the development server. This process requires Node.js version 18 or higher.
    # Clone the repository
git clone https://github.com/nisabmohd/Aria-Docs.git

# Enter the project directory
cd Aria-Docs

# Install dependencies
npm install

# Launch the development server
npm run dev

  6. Handle images in AriaDocs Markdown

    AriaDocs automatically transforms Markdown image syntax into the Next.js Image component. This provides built-in performance benefits including automatic image optimization, lazy loading, and resizing for responsive layouts.
    ![Alt text for the image](https://via.placeholder.com/150)

    // Rendered as:

    <Image
    src="https://via.placeholder.com/150"
    alt="Alt text for the image"
    width={800}
    height={350}
/>

  7. Use Server Actions for server-side logic in Next.js

    Server Actions are asynchronous functions that execute on the server in response to client-side events (like form submissions). They allow developers to handle sensitive operations and server-side logic without manually creating a separate API endpoint.
    // app/actions/submit.js
import { saveFormData } from "../lib/api";

export async function submitForm(data) {
  await saveFormData(data);
  return { success: true };
}

// contactForm.js
"use client";

import { submitForm } from "../actions/submitForm";

export default function ContactForm() {
  const handleSubmit = async (event) => {
    event.preventDefault();
    const formData = new FormData(event.target);
    // Call the server action directly
    const result = await submitForm(Object.fromEntries(formData));
    if (result.success) {
      alert("Form submitted successfully!");
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <label>
        Name:
        <input type="text" name="name" required />
      </label>
      <label>
        Email:
        <input type="email" name="email" required />
      </label>
      <button type="submit">Submit</button>
    </form>
  );
}

  8. Handle links in AriaDocs Markdown

    AriaDocs automatically converts standard Markdown links into Next.js Link components. This transformation enables client-side navigation and improves application loading times. External links are automatically assigned target="_blank" and rel="noopener noreferrer" attributes.
    [Visit OpenAI](https://www.openai.com)

    // Rendered as:

    <Link href="https://www.openai.com" target="_blank" rel="noopener noreferrer">
    Visit OpenAI
</Link>

  9. Quickly scaffold a new AriaDocs project using npx

    Use the create-aria-doc command via npx to quickly initialize a new AriaDocs project directory from the master branch. After the command completes, you must still navigate into the directory, install dependencies, and start the server.
    # Create the project
npx create-aria-doc <project-directory>

# Finalize setup
cd <project-directory>
npm install
npm run dev

  10. Create and publish blog posts

    Blog posts are created by adding .mdx files to the @content/blogs directory. Each blog post must include specific frontmatter (title, description, date, authors, and cover) to be rendered and sorted correctly on the blog listing page.
    ---
title: "Building a Recursive File System with React: A Deep Dive"
description: "Explore how to create a recursive file system in React..."
date: 02-09-2024
authors:
  - avatar: "https://ui.shadcn.com/avatars/02.png"
    handle: nisabmohd
    username: Nisab Mohd
    handleUrl: "https://github.com/nisabmohd"
cover: "https://img.freepik.com/premium-vector/many-monsters-various-colors-doodle-come-bless-birthday-happy_577083-84.jpg?w=826"
---

<!-- Your blog markdown content -->

  11. Create and register custom Markdown components in AriaDocs

    To use custom components within Markdown content in AriaDocs, you must create the component in the designated components folder and register it in the markdown library configuration.

    Steps to implement:

    1. Create the component file (e.g., Outlet.tsx) inside the @components/markdown directory.
    2. Import the component into the @lib/markdown.ts file.
    3. Add the component to the components object within @lib/markdown.ts to make it available to the Markdown renderer.
    4. Use the component directly in Markdown files using JSX-like syntax.
    // In @lib/markdown.ts
import Outlet from "@/components/markdown/outlet";

// Add custom components to the registration object
const components = {
  Outlet,
};
    <!-- Usage in a .md file -->
<Outlet>
  This is some custom content rendered by the Outlet component!
</Outlet>