:warning: This catalog is no longer maintained. There is a non-Polymer specific catalog available on https://www.webcomponents.org/ A self-hosting catalog is available at https://github.com/PolymerLabs/indie-catalog :warning:
To work on the Polymer Elements Catalog, clone the repository.
To install dependencies:
npm run deps
To start a local development server:
npm run serve
To start a local development server with fixtures
turned on:
FIXTURES=true npm run serve
To prepare the repo for publication:
npm run build
Note: Make sure that you're running chrome 42 or later!
While parts of the system are still in flux, it will be necessary to have stubbed
data and other bits to be able to work against. Anything in the fixtures
directory will be available when running a development server. By the time
the catalog ships, the fixtures
directory should be empty.
Data for the catalog is compiled by intelligently composing together information from multiple sources:
catalog.json
file in this repositorybower.json
for each element package and individual elementEach of these inputs is combined and compiled into a static format easily loaded by the catalog application. Outputs of the catalog compilation process include:
/data/catalog.json
file heavily annotated with parsed metadata/data/docs
/data/guides
catalog.json
is CreatedThe final catalog.json
file can be thought of as the repo's initial file
decorated substantially with metadata. For instance, a package in the initial
file:
{
"packages": [
{"title":"Iron Elements", "name":"iron-elements"}
]
}
Gets decorated with metadata parsed from its' bower.json
:
{
"packages": [
{
"title":"Iron Elements",
"name":"iron-elements",
"description":"Polymer core elements",
"version":"1.0.0",
"tags":["utility","scaffolding","user-input"]
}
]
}
This decoration occurs in steps and can be considered a series of merges.
Each set of elements (henceforth "package") is responsible for maintaining its
own documentation according to the conventions established elsewhere in this
document. Each package is represented in catalog.json
as an entry in an array.
This array corresponds to the order in which packages are presented in nav
contexts in the element catalog. Each package has the following associated data:
bower.json
Each named package should be declared as a dependency in the bower.json
for
this repository. Additionally, each package's version number should be explicit,
as the version declared in bower.json
is used as display text in the catalog.
{
// correct example
"iron-elements": "PolymerElements/iron-elements#1.0.0"
// incorrect example
"paper-elements": "PolymerElements/paper-elements#^1.0"
}
By maintaining strict versioning in the catalog, updating a package's data
becomes as easy as a pull request to bower.json
.
As much as possible, the element catalog uses existing conventions from systems such as Bower as a repository for metadata.
The bower.json
for a package should contain a dependencies
entry for each of
its child elements. A declared dependency will be considered a child element of
the package if and only if its name is identical to the package name before the
first dash. As an example, if the package is iron-elements
, iron-ajax
would
be considered a child but polymer
would not.
The element catalog uses the following information from bower.json
:
packages
entry in the
catalog.json
file in this repository for it to be displayed.web-components
and polymer
, these keywords will be
used as tags in the final catalog data.Elements behave much like packages: they are responsible for maintaining their
own documentation in bower.json
. In addition, the source .html
files for
elements should be documented in accordance with the Polymer Elements style guide.
The catalog uses the following information from an element's bower.json
:
.html
file of the same name that contains the element or imports all default elements
for element repos with multiple elements.web-components
and polymer
, these keywords will
be used as tags in the final catalog data.iron-icons
each icon set might be imported
separately, so each set should be included in main. For many (most) elements
this can just be a string with the .html
filename matching the name
field.Guides are in-depth articles that allow for article-style documentation in addition to the API documentation for each element parsed using hydrolysis.
Guides are simply Markdown files with YAML front-matter and can be included
in the repository for the catalog, a package, or an individual element. To
avoid namespace collisions, guides for packages and individual elements are
identified with repo-name/guide-name
, while guides in this repository are
identified simply with guide-name
.
Each guide will be listed and accessible in the Guides section of the catalog, and will additionally be associated with each element and package it references.
bower_components/gold-elements/guides/ecommerce.md
)---
title: How to Build an E-Commerce Site with Gold Elements
summary: "Learn how to add drop-in E-commerce components to quickly build a web presence for your business."
tags: ['ecommerce','beginner']
elements: ['gold-checkout','paper-input']
updated: 2015-04-10
---
Actual article content starts here.
## Example Section
Etc. etc.
catalog.json
{
// guides with associated packages should also be referenced in the package metadata
"packages": [
{"name":"gold-elements","guides":["gold-elements/ecommerce"]}
],
"guides": [
{
"name":"gold-elements/ecommerce",
"title":"How to Build an E-Commerce Site with Gold Elements",
"tags":["ecommerce","beginner"],
"elements":["gold-checkout","paper-input"],
"package":"gold-elements"
}
],
"elements": [
{"name":"paper-input","guides":["gold-elements/ecommerce"]}
]
}
If a guide needs images or other assets, those should be stored in /guides/assets
in the repository and always referenced with relative URLs (e.g. assets/filename.jpg
).
By maintaining this convention the catalog compilation process will automatically
ensure that images and other assets are properly accessible to the guide.