How nypl/metadata-documentation works
This project is a documentation website built to house and present best practices, workflows, guidelines, and reference materials for NYPL’s Metadata Services Unit. From the file tree and the README, we can deduce that the site is statically generated (likely using Jekyll, given the presence of a Gemfile, _config.yml, and Markdown content files) and is organized into several thematic sections (e.g., metadata, workflows, system, projects, colophon, etc.).
Project’s Main Components
• Static Site Generator: Represent the tool (likely Jekyll) that reads configuration (_config.yml), uses Gemfile-managed dependencies, processes Markdown (.md) files, and builds the final static site.
• Content Sections: Group content by thematic areas visible in the file tree:
• Metadata: Contains guidelines, definitions and standardized content for metadata (the “metadata” folder with subdirectories like “element”, “material”, etc.).
• Workflows: Contains documentation on digitization, importing, remediation, rights, etc.
• System: Documentation on internal systems like accounts, training, and overall system operations.
• Projects, Colophon, DC (document control), and Contact: Other sections of the documentation site.
• Shared Components & Assets: Including the _includes (for reusable HTML snippets like head and footer navigation), the assets folder (images, JavaScript), and configuration templates.
• External Repositories: The README mentions related internal repos (metadata-admin, metadata-projects, metadata-tools) that could be noted as external resources or integrations.
Relationships and Interactions
• The Static Site Generator (Jekyll) takes input from the Markdown files, the _includes folder, and the assets folder. It then processes these inputs guided by _config.yml and Gemfile, resulting in the final rendered website.
• The content directories are “plugged into” the site’s structure—each with specific purposes (for example, workflows detail operational procedures while metadata focuses on technical elements).
• There is a logical navigation flow between the sections (e.g., the navigation and footer included in _includes provide links to all major sections).
• External links (mentioned in the README) highlight the relationship between public documentation and internal repositories.
Architectural Patterns & Design Principles
• Static Site Generation: Emphasize that the architecture relies on pre-building content from Markdown into HTML.
• Separation of Concerns: The project clearly distinguishes between content (Markdown files organized by topic), presentation (custom HTML snippets in _includes and assets), and configuration (via _config.yml and Gemfile).
• Modularity and Extensibility: Multiple directories and subdirectories indicate the project is organized into modular topics that can be independently maintained and expanded.