PDF Services API (adobedocs/pdfservices-api-documentation)

PDF Services API

https://github.com/adobedocs/pdfservices-api-documentation
Admin
This project provides documentation for the Adobe PDF Services API, which allows developers to...

Tokens:918,337
Snippets:3,185
Trust Score:8
Update:5 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Adobe PDF Services API Documentation Site

## Introduction

This is the Adobe PDF Services API Documentation Site, a comprehensive developer documentation platform built with Gatsby 4.22 and React 17. The project serves as the central documentation hub for Adobe Acrobat Services APIs, including PDF Services API, PDF Extract API, Document Generation API, PDF Accessibility Auto-Tag API, PDF Electronic Seal API, PDF Embed API, Sign API, and the Power Automate Connector. It provides developers with API references, quickstart guides, how-to tutorials, and code examples across multiple programming languages (Node.js, Java, Python, and .NET).

The site leverages Adobe's Gatsby Theme AIO (@adobe/gatsby-theme-aio) for consistent design patterns and component architecture. It features full-text search powered by Algolia, Adobe Identity Management System (IMS) integration for authentication, comprehensive analytics tracking through Adobe Launch and Google Analytics, and is deployed to Azure Blob Storage with Fastly CDN for global content delivery. The documentation covers everything from getting started guides to advanced use cases for PDF manipulation, document generation from templates, accessibility tagging, electronic sealing, and embedded PDF viewing with analytics.

---

## Development Environment

### Local Development Setup

```bash
# Install dependencies (must use yarn, not npm)
yarn install

# Start development server
npm run dev

# Access local site
# Open http://localhost:8000/overview in browser

# Optional: Increase Node.js memory limit if needed
export NODE_OPTIONS=--max_old_space_size=8192
```

### Build Commands

```bash
# Production build
gatsby build

# Build with path prefix
gatsby build --prefix-paths && gatsby serve --prefix-paths

# Clean build cache
gatsby clean

# Incremental build (experimental)
GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES=true gatsby build --log-pages

# Validate internal links
npm run test:links

# Run linter
npm run lint
```

---

## Site Configuration

### Gatsby Config Structure (gatsby-config.js)

```javascript
module.exports = {
  flags: {
    DEV_SSR: false
  },
  siteMetadata: {
    docs: {
      title: 'Get credentials',
      path: 'https://acrobatservices.adobe.com/dc-integration-creation-app-cdn/main.html'
    },
    pages: [
      {
        title: 'Adobe Acrobat Services',
        subTitle: '',
        path: '../../../document-services/'
      },
      {
        title: 'APIs',
        menu: [
          {
            title: 'PDF Services',
            description: 'Create, combine and export PDFs',
            path: '../document-services/apis/pdf-services/'
          },
          {
            title: 'PDF Extract',
            description: 'Extract text, tables, images, and document structure',
            path: '../document-services/apis/pdf-extract/'
          },
          {
            title: 'Document Generation',
            description: 'Generate PDF and Word documents from custom Word templates',
            path: '../document-services/apis/doc-generation/'
          }
        ]
      }
    ],
    subPages: [
      {
        title: 'PDF Services API',
        path: 'overview/pdf-services-api/index.md',
        pages: [
          {
            title: 'Quickstarts',
            path: 'overview/pdf-services-api/quickstarts',
            pages: [
              { title: 'Node.js', path: 'overview/pdf-services-api/quickstarts/nodejs/index.md' },
              { title: 'Java', path: 'overview/pdf-services-api/quickstarts/java/index.md' },
              { title: '.NET', path: 'overview/pdf-services-api/quickstarts/dotnet/index.md' },
              { title: 'Python', path: 'overview/pdf-services-api/quickstarts/python/index.md' }
            ]
          }
        ]
      }
    ]
  },
  plugins: [
    '@adobe/gatsby-theme-aio'
  ]
};
```

---

## Layout Component

### Main Layout Wrapper (src/@adobe/gatsby-theme-aio/components/Layout/index.js)

```javascript
import React, { createElement, useEffect, useState } from 'react';
import { Helmet } from 'react-helmet';
import { css, Global } from '@emotion/react';
import algoliaSearch from 'algoliasearch';
import { graphql, useStaticQuery } from 'gatsby';
import { Provider } from '@adobe/gatsby-theme-aio/src/components/Context';
import { SideNav } from '../SideNav';
import { GlobalHeader } from '@adobe/gatsby-theme-aio/src/components/GlobalHeader';
import { SEO } from '../SEO';

// Initialize Algolia search if configured
const hasSearch = !!(
  process.env.GATSBY_ALGOLIA_APPLICATION_ID &&
  process.env.GATSBY_ALGOLIA_SEARCH_API_KEY
);

let algolia = null;
if (hasSearch) {
  algolia = algoliaSearch(
    process.env.GATSBY_ALGOLIA_APPLICATION_ID,
    process.env.GATSBY_ALGOLIA_SEARCH_API_KEY
  );
}

// Check for Adobe IMS authentication
const hasIMS = !!(process.env.GATSBY_IMS_SRC && process.env.GATSBY_IMS_CONFIG);

// Helper function to get query string from URL
export const getQueryString = () => {
  const params = new URLSearchParams(window.location.search);
  return params.toString();
};

// Main Layout component with side navigation and content area
const Layout = ({ children, pageContext, location }) => {
  const [showSideNav, setShowSideNav] = useState(false);
  const [isLoading, setIsLoading] = useState(false);

  return (
    <Provider>
      <SEO />
      <GlobalHeader />
      <div className="main-grid">
        <SideNav
          selectedPages={selectedPages}
          selectedSubPages={selectedSubPages}
          setShowSideNav={setShowSideNav}
        />
        <main className="content-area">
          {children}
        </main>
      </div>
    </Provider>
  );
};

export default Layout;
```

---

## Side Navigation Component

### Hierarchical Navigation Renderer (src/@adobe/gatsby-theme-aio/components/SideNav/index.js)

```javascript
import React, { useState } from 'react';
import { Link as GatsbyLink } from 'gatsby';
import { css } from '@emotion/react';
import classNames from 'classnames';
import '@spectrum-css/sidenav';

const SideNav = ({ selectedPages, selectedSubPages, setShowSideNav }) => {
  const [expandedPages, setExpandedPages] = useState([]);

  // Custom subtitle renderer with visual badge
  const handleSubtile = (title) => {
    return (
      <div>
        {title.title}
        <span style={{
          display: "inline-block",
          color: 'red',
          fontSize: '10px',
          border: '1px solid',
          padding: '2px',
          marginLeft: '3px'
        }}>
          {title.subTitle}
        </span>
      </div>
    );
  };

  const renderSubtree = (pages, level) =>
    pages
      .filter((page) => page.title && page.href)
      .map((page, index) => {
        const isSelected = selectedPages.find((selectedItem) => selectedItem === page);

        return (
          <li
            key={index}
            className={classNames([
              'spectrum-SideNav-item',
              { 'is-expanded': page.header || expandedPages.includes(page.href) },
              { 'is-selected': selectedPages[selectedPages.length - 1] === page && isSelected }
            ])}
          >
            <GatsbyLink
              onClick={(event) => {
                if (page?.pages?.length && !page.header) {
                  event.preventDefault();
                  if (expandedPages.includes(page.href)) {
                    setExpandedPages((pages) => pages.filter((href) => href !== page.href));
                  } else {
                    setExpandedPages([...expandedPages, page.href]);
                  }
                } else {
                  setShowSideNav(false);
                }
              }}
              to={page.href}
              className="spectrum-SideNav-itemLink"
              role="treeitem"
              aria-level={level}
            >
              {!page.subTitle ? page.title : handleSubtile(page)}
            </GatsbyLink>
            {page.pages && (
              <ul className="spectrum-SideNav">
                {renderSubtree(page.pages, level + 1)}
              </ul>
            )}
          </li>
        );
      });

  return (
    <nav className="spectrum-SideNav">
      <ul className="spectrum-SideNav">
        {renderSubtree(selectedSubPages, 1)}
      </ul>
    </nav>
  );
};

export default SideNav;
```

---

## Analytics Integration

### Route Tracking (gatsby-browser.js)

```javascript
const isBrowser = typeof window !== "undefined";

export const onRouteUpdate = ({ location, prevLocation }) => {
  if (isBrowser) {
    let siteSection = location.pathname.split("/");

    // Update Digital Data Layer for Adobe Analytics
    try {
      if (window.digitalData?.page?.pageInfo) {
        window.digitalData.page.pageInfo.siteSection =
          siteSection.pop() || siteSection.pop();

        window.digitalData.page.pageInfo.breadCrumbs = [];
        document.querySelectorAll(".spectrum-Breadcrumbs-item").forEach((item) => {
          window.digitalData.page.pageInfo.breadCrumbs.push(item.innerText);
        });
      }
    } catch (err) {
      console.error("Unable to set site section", err);
    }

    // Track page view with Adobe Satellite
    try {
      if (window._satellite && window.digitalData) {
        window._satellite.track("state", {
          digitalData: window.digitalData._snapshot(),
        });
      }
    } catch (err) {
      console.error("Unable to set state", err);
    }

    // Set DAA (Digital Analytics and Attributes) tags on header links
    let header = document.querySelector("header");
    header.setAttribute("daa-lh", "Gnav");
    header
      .querySelector("a[href='/']")
      ?.setAttribute("daa-ll", "Adobe Developer");
    header
      .querySelector("a[href='/apis/']")
      ?.setAttribute("daa-ll", "Products");
    header
      .querySelector("a[href='/document-services/']")
      ?.setAttribute("daa-ll", "Adobe Acrobat Services");
  }
};
```

---

## CI/CD Deployment

### GitHub Actions Workflow (.github/workflows/deploy.yml)

```yaml
name: Deployment
on:
  workflow_dispatch:
    inputs:
      env:
        description: "Deploy to (dev|prod|dev prod)"
        required: true
        default: "dev"
      clean:
        description: "Clean cache (yes|no)"
        required: true
        default: "no"

jobs:
  build-dev:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup Node v16 for Yarn v3
        uses: actions/setup-node@v3
        with:
          node-version: "16.15.0"

      - name: Enable Corepack for Yarn v3
        run: corepack enable

      - name: Install Dependencies
        run: yarn install

      - name: Build Gatsby Site
        run: gatsby build
        env:
          NODE_OPTIONS: --max_old_space_size=8192
          GATSBY_ALGOLIA_APPLICATION_ID: ${{ secrets.ALGOLIA_APP_ID }}
          GATSBY_ALGOLIA_SEARCH_API_KEY: ${{ secrets.ALGOLIA_SEARCH_KEY }}
          GATSBY_ALGOLIA_INDEX_ENV_PREFIX: dev
          GATSBY_IMS_SRC: ${{ secrets.IMS_SRC }}
          GATSBY_IMS_CONFIG: ${{ secrets.IMS_CONFIG }}
          GATSBY_ADOBE_LAUNCH_SRC: ${{ secrets.ADOBE_LAUNCH_SRC }}
          REPO_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          REPO_OWNER: AdobeDocs
          REPO_NAME: ${{ github.event.repository.name }}
          REPO_BRANCH: ${{ github.ref_name }}

      - name: Deploy to Azure Blob Storage
        uses: azure/CLI@v1
        with:
          azcliversion: 2.30.0
          inlineScript: |
            az storage blob upload-batch \
              --account-name ${{ secrets.AZURE_STORAGE_ACCOUNT }} \
              --destination '$web' \
              --source ./public \
              --connection-string "${{ secrets.AIO_AZURE_DEV_CONNECTION_STRING }}"

      - name: Purge Fastly CDN Cache
        run: |
          curl -X POST "https://api.fastly.com/service/${{ secrets.FASTLY_SERVICE_ID }}/purge_all" \
            -H "Fastly-Key: ${{ secrets.FASTLY_API_KEY }}" \
            -H "Accept: application/json"
```

---

## Environment Variables

### Required Configuration (.env.example)

```bash
# GitHub Integration
REPO_GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
REPO_OWNER=AdobeDocs
REPO_NAME=dev-site-documentation-template
REPO_BRANCH=main

# Algolia Search (optional)
GATSBY_ALGOLIA_APPLICATION_ID=XXXXXXXXXX
GATSBY_ALGOLIA_SEARCH_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GATSBY_ALGOLIA_INDEX_ENV_PREFIX=prod

# Adobe IMS Authentication (optional)
GATSBY_IMS_SRC=https://auth.services.adobe.com/imslib/imslib.js
GATSBY_IMS_CONFIG={"client_id":"xxx","scope":"xxx"}

# Adobe Analytics (optional)
GATSBY_ADOBE_LAUNCH_SRC=https://assets.adobedtm.com/launch-xxx.min.js
GATSBY_ADOBE_LAUNCH_PROD_SRC=https://assets.adobedtm.com/launch-xxx.min.js

# Performance
NODE_OPTIONS=--max_old_space_size=8192
```

---

## Content Structure

### Markdown Page with Front Matter (src/pages/overview/index.md)

```markdown
---
title: Adobe PDF Services
---

# Introduction

## What are Acrobat Services APIs?

Adobe Acrobat Services has five main APIs: PDF Services API, PDF Embed API,
Document Generation API, PDF Extract API and PDF Accessibility Auto-Tag API.
These APIs automate the generation, manipulation, and transformation of document
content via modern cloud-based web services.

## PDF Services API

The [PDF Services API](pdf-services-api) offers operations to programmatically
manipulate documents and automate document workflows. You can:

- Create PDFs from dynamic HTML reports
- Set passwords to prevent unauthorized access
- Compress files for sharing
- Extract text, tables, images and document structure
- Compress or linearize for faster web viewing
- Insert, reorder, rotate, replace, and delete pages

Free Tier includes 500 free Document Transactions per month.

## Document Generation API

The [Document Generation API](document-generation-api) allows you to produce
high fidelity PDF and Word documents with dynamic data inputs. Merge JSON data
with Word templates to create dynamic documents for contracts, invoices,
proposals, reports, forms, and marketing materials.
```

---

## Package Configuration

### Dependencies (package.json)

```json
{
  "name": "dev-site-documentation-template",
  "version": "1.0.0",
  "license": "Apache-2.0",
  "repository": {
    "type": "git",
    "url": "https://github.com/AdobeDocs/dev-site-documentation-template"
  },
  "dependencies": {
    "@adobe/gatsby-theme-aio": "^4.14.14",
    "gatsby": "4.22.0",
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  },
  "resolutions": {
    "sharp": "0.33.0",
    "gatsby-sharp": "1.12.0"
  },
  "scripts": {
    "dev": "gatsby develop",
    "build": "gatsby build",
    "serve": "gatsby serve",
    "clean": "gatsby clean",
    "test:links": "remark src/pages --quiet --frail"
  },
  "devDependencies": {
    "remark-cli": "^11.0.0",
    "remark-validate-links": "^12.1.0"
  },
  "packageManager": "yarn@1.22.21"
}
```

---

## GraphQL Data Queries

### Fetching Navigation and Content Data

```javascript
import { graphql, useStaticQuery } from 'gatsby';

// Query all markdown pages and site metadata
const data = useStaticQuery(graphql`
  query {
    allMdx {
      nodes {
        tableOfContents
        fileAbsolutePath
        frontmatter {
          title
          description
          openAPISpec
          frameSrc
        }
      }
    }
    allSitePage {
      nodes {
        path
        componentPath
      }
    }
    site {
      siteMetadata {
        pages {
          title
          path
          menu {
            title
            description
            path
          }
        }
        subPages {
          title
          path
          pages {
            title
            path
          }
        }
      }
    }
    allGithub {
      nodes {
        repository
        default_branch
        root
      }
    }
    allGithubContributors {
      nodes {
        contributors {
          login
          avatar_url
          html_url
        }
      }
    }
  }
`);

// Use data to build navigation structure
const pages = data.site.siteMetadata.pages;
const subPages = data.site.siteMetadata.subPages;
```

---

## Styling and Theming

### Custom CSS Overrides (src/styles/main.css)

```css
/* Left-align title block */
.titleBlock {
  text-align: left;
}

/* Responsive adjustments for mobile */
@media screen and (max-width: 768px) {
  .titleBlock {
    padding: 16px;
  }

  .titleBlock h1 {
    font-size: 28px;
  }
}

/* Custom badge styling for disclaimers */
.disclaimer-badge {
  display: inline-block;
  color: red;
  font-size: 10px;
  border: 1px solid red;
  padding: 2px 4px;
  margin-left: 8px;
  border-radius: 2px;
}
```

---

## Algolia Search Configuration

### Search Integration with React

```javascript
import algoliaSearch from 'algoliasearch';
import { Search } from '@adobe/gatsby-theme-aio/src/components/Search';

// Initialize Algolia client
const algolia = algoliaSearch(
  process.env.GATSBY_ALGOLIA_APPLICATION_ID,
  process.env.GATSBY_ALGOLIA_SEARCH_API_KEY
);

// Configure search indices
const searchIndices = JSON.parse(process.env.GATSBY_ALGOLIA_SEARCH_INDEX || '[]');
const algoliaIndexEnv = process.env.GATSBY_ALGOLIA_INDEX_ENV_PREFIX; // prod, stage, dev

// Example: prod_pdf_services, stage_pdf_services
const indexPrefix = algoliaIndexEnv ? `${algoliaIndexEnv}_` : '';

// Search component usage
<Search
  algolia={algolia}
  indices={searchIndices}
  indexPrefix={indexPrefix}
  searchButtonLabel="Search Documentation"
/>
```

---

## Summary

This Adobe PDF Services API Documentation Site is a production-grade, enterprise-level documentation platform that demonstrates modern Jamstack architecture principles. The primary use cases include providing comprehensive API documentation for developers integrating Adobe's PDF manipulation services, offering quickstart guides and code samples across multiple programming languages, and serving as a central knowledge base for PDF Services, Document Generation, PDF Extract, and related Adobe APIs. The site supports developer onboarding with step-by-step tutorials, API reference materials, and interactive examples that developers can copy and implement directly in their applications.

The integration patterns employed include Gatsby's static site generation for optimal performance and SEO, Adobe's Spectrum CSS design system for consistent UI components, Algolia for powerful full-text search capabilities, Adobe IMS for enterprise authentication, and Azure Blob Storage with Fastly CDN for global content delivery. The GitHub Actions CI/CD pipeline enables automated builds and deployments with environment-specific configurations for development and production. The modular component architecture allows for easy customization and extension, with shadowing support for overriding default theme components. Analytics integration provides deep insights into user behavior and content engagement, while the markdown-based content structure enables technical writers and developers to contribute documentation using familiar tools and version control workflows.