SEO оптимизация документации

Библиотеки Remark и Rehype обеспечивают мощный инструментальный набор для обработки Markdown и HTML, что делает их ключевыми компонентами при SEO-оптимизации документации. Основная цель заключается в корректной трансформации контента, добавлении семантики и возможности интеграции метаданных для улучшения индексации поисковыми системами.

Установка и базовая конфигурация

Для работы с Remark и Rehype требуется установка нескольких пакетов:

npm install remark remark-html rehype rehype-stringify unified

Здесь:

  • remark — ядро для парсинга Markdown.
  • remark-html — плагин для конвертации в HTML.
  • rehype — система для обработки HTML AST (Abstract Syntax Tree).
  • rehype-stringify — финальный этап превращения AST в строку HTML.

Основной поток обработки

  1. Парсинг Markdown Remark преобразует Markdown в дерево синтаксиса (MDAST). В этом дереве каждая структура документа (заголовки, параграфы, списки) представлена отдельными узлами.

  2. Преобразование в HTML Плагин remark-html превращает MDAST в HTML. Этот этап является критическим для SEO, так как позволяет управлять семантикой тегов:

    • Заголовки <h1>…<h6> определяют иерархию контента.
    • Параграфы <p> сохраняют читабельность.
    • Списки <ul>, <ol> формируют структурированное содержание.

  3. Обработка Rehype Rehype работает с HTML AST, что позволяет внедрять дополнительные улучшения:

    • Добавление атрибутов alt для изображений.
    • Генерация ссылок с атрибутом rel="nofollow" для внешних источников.
    • Вставка микроразметки Schema.org для улучшенной индексации.

Пример минимального конвейера:

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkHtml from 'remark-html';
import rehypeRaw from 'rehype-raw';
import rehypeStringify from 'rehype-stringify';

const processor = unified()
  .use(remarkParse)
  .use(remarkHtml)
  .use(rehypeRaw)        // позволяет Rehype обрабатывать вставленный HTML
  .use(rehypeStringify);

const markdown = `# Заголовок уровня 1
Параграф с описанием функции.`;

processor.process(markdown).then(file => {
  console.log(String(file));
});

Оптимизация заголовков и структуры

SEO напрямую зависит от правильной структуры заголовков. Для этого можно использовать плагин remark-slug, который автоматически генерирует идентификаторы для заголовков:

import remarkSlug from 'remark-slug';

unified()
  .use(remarkParse)
  .use(remarkSlug)
  .use(remarkHtml);

Преимущество: каждый заголовок получает id, что позволяет создавать якорные ссылки и улучшает индексирование.

Работа с метаданными

Документация часто требует установки мета-тегов <title> и <meta> для описания страницы и ключевых слов. Rehype предоставляет возможность интеграции этих тегов через AST:

import rehypeDocument from 'rehype-document';

unified()
  .use(remarkParse)
  .use(remarkHtml)
  .use(rehypeDocument, {
    title: 'Документация по Remark/Rehype',
    meta: [
      { name: 'description', content: 'Подробное руководство по Remark и Rehype' },
      { name: 'keywords', content: 'javascript, markdown, seo, rehype, remark' }
    ]
  })
  .use(rehypeStringify);

Автоматическая генерация оглавления

Для улучшения навигации и SEO можно автоматически создавать оглавление документации. Remark позволяет собрать все заголовки и сгенерировать дерево ссылок:

import remarkToc from 'remark-toc';

unified()
  .use(remarkParse)
  .use(remarkSlug)
  .use(remarkToc, { heading: 'Содержание' })
  .use(remarkHtml);

Интеграция микроразметки

Schema.org микроразметка повышает видимость документации в поисковой выдаче. Rehype позволяет вставлять микроразметку прямо в HTML AST:

import rehypeAddAttributes from 'rehype-add-attributes';

unified()
  .use(remarkParse)
  .use(remarkHtml)
  .use(rehypeAddAttributes, { 'article': { itemscope: true, itemtype: 'https://schema.org/TechArticle' } })
  .use(rehypeStringify);

Производительность и оптимизация

Для больших документаций важна оптимизация:

  • lazy processing: обработка отдельных файлов Markdown по мере необходимости.
  • caching AST деревьев для повторного использования.
  • плагин remark-frontmatter: позволяет хранить метаданные в начале документа, что ускоряет генерацию SEO-тегов.

Интеграция с современными фреймворками

Remark и Rehype легко интегрируются с React, Vue, Next.js или Astro. Компоненты могут рендерить Markdown с сохранением всех SEO-атрибутов, обеспечивая:

  • динамическое добавление заголовков и описаний;
  • безопасное внедрение HTML с rehype-sanitize;
  • генерацию статических страниц с готовой SEO-структурой.

Резюме ключевых возможностей

  • Remark парсит и структурирует Markdown в AST.

  • Rehype позволяет обогащать HTML семантикой и микроразметкой.

  • Плагины Remark/Rehype обеспечивают:

    • генерацию идентификаторов заголовков (remark-slug),
    • автоматическое содержание (remark-toc),
    • вставку мета-тегов и микроразметки (rehype-document, rehype-add-attributes),
    • безопасную обработку HTML (rehype-sanitize).

  • Возможность интеграции с современными фреймворками делает систему гибкой для любых проектов документации.

Эта комбинация инструментов создаёт основу для SEO-оптимизированной документации, обеспечивая семантически корректный HTML и улучшенную индексацию поисковыми системами.

Оглавление