DOCSEARCHbyAlgolia
Submit Docs

htmldocs Documentation

repository·canary·Indexed 20 days ago

https://github.com/htmldocs-js/htmldocs

A modern PDF generation tool for creating structured documents using React, TypeScript, and Tailwind CSS. htmldocs utilizes the Chromium rendering engine and Paged.js for professional typesetting, offering a JSX-based templating system, a local development server, and a cloud API for programmatic document generation.

Tokens
24.3K
Snippets
88
Records
116
Agent score
72%

What's inside htmldocs

  1. What is htmldocs?

    canary

    htmldocs is a modern PDF document generation system designed for a developer-centric workflow. It replaces traditional tools like Word or LaTeX by using React, TypeScript, and Tailwind CSS to build documents.

    Key capabilities include:

    • JSX Templating: Build dynamic documents using React components.
    • Modern CSS: Support for flexbox and advanced features like margin boxes.
    • Type Safety: Full TypeScript support for document structures.
    • Dynamic Data: Integration of data via props and APIs.
    • Real-time Preview: A development server with hot reloading for instant feedback.

  3. Compare htmldocs with other document solutions

    canary

    htmldocs provides a highly structured, developer-friendly alternative to traditional, freeform, or LaTeX-based document creation. Key advantages include support for template variables, automation via APIs, developer plugins, type safety, and full CI/CD integration.

    | Feature | Traditional Documents (Word, Google Docs) | LaTeX Documents (Overleaf, TeXStudio) | Freeform Documents (Figma, Sketch) | Web Documents (htmldocs) |
|---------|:-------------------------------------------:|:----------------------------------------:|:-------------------------------------:|:---------------------------:|
| Content Structure | Semi-Structured | Highly Structured | Freeform | Highly Structured |
| Learning Curve | ✅ Simple | ❌ Complex | ✅ Simple | ✅ Simple |
| Template Variables | ❌ Limited | ❌ Limited | ❌ Limited | ✅ Supported |
| Styling | ✅ Basic | ❌ Complex | ✅ Advanced | ✅ Advanced |
| Version Control | ❌ Limited | ✅ Supported | ❌ Limited | ✅ Supported |
| Document Consistency | ❌ Limited | ✅ Supported | ✅ Supported | ✅ Supported |
| External Libraries | ❌ Limited | ✅ Supported | ❌ Limited | ✅ Supported |
| Automation / API | ❌ Limited | ❌ Limited | ❌ Limited | ✅ Supported |
| Developer Plugins | ❌ Limited | ❌ Limited | ❌ Limited | ✅ Supported |
| Live Preview | ✅ Supported | ❌ Limited | ✅ Supported | ✅ Supported |
| CI/CD Integration | ❌ Limited | ⚠️ Partial | ❌ Limited | ✅ Supported |
| Type Safety | ❌ Limited | ❌ Limited | ❌ Limited | ✅ Supported |
| AI Integrations | ❌ Limited | ❌ Limited | ❌ Limited | ✅ Supported |

  5. How htmldocs renders documents

    canary

    htmldocs is built upon the Chromium rendering engine, enabling it to render any standard HTML, CSS, and JavaScript. This provides broader compatibility compared to tools like wkhtmltopdf or WeasyPrint.

    Additionally, it utilizes the Paged.js library for layout, chunking, and advanced features like margin boxes that extend beyond standard W3C CSS support.

  6. Publish documents to the cloud

    canary

    The publish <file> command uploads your document to the cloud for API use.

    Requirements:

    • You must be authenticated via login.
    • You must run this command from the root of your project.

    Arguments:

    • file (string, required): The file path of the document to publish.
    npx htmldocs@latest publish <file>

  7. Setup htmldocs manually in an existing project

    canary

    To integrate htmldocs into an existing React/TypeScript project, follow these steps:

    1. Install dependencies: Install htmldocs, @htmldocs/react, and @htmldocs/render.
    2. Add dev script: Add the dev script to your package.json to enable the htmldocs development server.
    3. Create document template: Create a documents folder and define a document component (e.g., Book.tsx) using the @htmldocs/react components.
    4. Run development server: Execute your dev script to start the live preview.
    npm install htmldocs @htmldocs/react @htmldocs/render

# Add to package.json:
{
    "scripts": {
        "dev": "npx htmldocs@latest dev"
    }
}

# Run the server:
npm run dev

  8. When to choose htmldocs

    canary

    htmldocs is designed for developers and teams who require a code-first approach to documentation. It is the ideal choice when your workflow requires:

    • Programmatic Generation: Creating documents dynamically using data and code.
    • Consistent Branding: Using components to maintain uniform styling across all documents.
    • Modern Development Ecosystem: Leveraging React, TypeScript, and the npm ecosystem.
    • CI/CD Integration: Automating document updates through CI/CD pipelines.
    • Version Control: Using Git to track changes and facilitate collaboration.
    • Developer-First Workflows: Using familiar tools in a code-driven environment.
    • AI Integration: Seamlessly generating content with AI tools like Cursor or Copilot.
    • Structured Layouts: Creating documents with precise typesetting and predictable, highly structured layouts.

  9. Authenticate the CLI with the cloud

    canary

    Use the login command to authenticate your CLI with the htmldocs cloud service. This is a required step before you can use the publish command. Running this command will open a browser window for you to select a team and complete authentication; tokens are stored securely for future use.

    npx htmldocs@latest login

  11. Use template variables in JSX templates

    canary

    You can create dynamic documents by defining template components that accept props. These props act as template variables that can be injected into your JSX content using standard React patterns. Wrap your template content in the <Document> component from @htmldocs/react to ensure it is processed correctly.

    import { Document } from "@htmldocs/react";

interface InvoiceProps {
  customerName: string;
  items: { 
    name: string; 
    quantity: number; 
    price: number; 
  }[];
}

function Invoice({ customerName, items }: InvoiceProps) {
  return (
    <Document>
      <h1>Invoice for {customerName}</h1>
      <div className="items">
        {items.map((item, index) => (
          <div key={index} className="item">
            <span>{item.name}</span>
            <span>{item.quantity}</span>
            <span>${item.price}</span>
          </div>
        ))}
      </div>
    </Document>
  );
}

export default Invoice;

  12. Preview documentation changes locally with Mintlify CLI

    canary

    To preview your documentation changes locally before deploying, use the Mintlify CLI. This allows you to render changes in a local environment to ensure they look as intended.

    1. Install the Mintlify CLI globally via npm:
      npm i -g mintlify
    2. Navigate to the root of your documentation directory (the folder containing your mint.json file).
    3. Run the development server:
      mintlify dev
    npm i -g mintlify
mintlify dev