16adda8c47
- Changed references in markup.md to update "data.html" to "data/" for clarity. - Updated metadata.md to correct the link to the general documentation. - Modified navbar.md to ensure stub values match the new permalink structure. - Adjusted tables.md to reflect the new permalink for the table visualization page. - Updated about.md to change the permalink from "/about.html" to "/about/" and revised content for clarity and impact. - Changed browse.md permalink from "/browse.html" to "/browse/" for consistency. - Added copyright.md page with copyright information and terms of use. - Updated data.md to change permalink from "/data.html" to "/data/" and added introductory content. - Created donate.md page to facilitate donations and acknowledge supporters. - Updated locations.md permalink from "/locations.html" to "/locations/" for consistency. - Changed map.md permalink from "/map.html" to "/map/" for uniformity. - Added erasure.md page discussing the historical context of Black queer Kansas Citians. - Updated out-there.md to correct the link to Lea Hopkins' interview. - Changed subjects.md permalink from "/subjects.html" to "/subjects/" for consistency. - Updated timeline.md permalink from "/timeline.html" to "/timeline/" for uniformity.
105 lines
6.2 KiB
Markdown
105 lines
6.2 KiB
Markdown
# Rich markup
|
|
|
|
Pages in CollectionBuilder contain machine readable rich markup following several standards to improve discoverability, search representation, and social media sharing.
|
|
|
|
## Dublin Core
|
|
|
|
Dublin Core elements are added to Item pages driven by the "dc_map" column of config-metadata.csv.
|
|
|
|
Choose mapping options directly from the DCMI Terms namespace: http://purl.org/dc/terms/
|
|
*Note: DMCI the original 15 Elements namespace is mirrored in the Terms namespace (i.e. both have "title", "creator", etc), however, using the newer Terms namespace is preferred.*
|
|
|
|
The values will be directly added to meta tag name attribute, thus should use the `DCTERMS` prefix.
|
|
|
|
For example, to use Dublin Core [Title](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/title) from the "Terms" namespace, the value would be `DCTERMS.title`.
|
|
To use [abstract](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/abstract), `DCTERMS.abstract`.
|
|
If the "dc_map" column is empty, no DC meta tags will be added.
|
|
|
|
Recommended fields to map include:
|
|
|
|
- `DCTERMS.title`
|
|
- `DCTERMS.creator`
|
|
- `DCTERMS.created` or `DCTERMS.date`
|
|
- `DCTERMS.description`
|
|
- `DCTERMS.subject`
|
|
- `DCTERMS.type`
|
|
|
|
This implementation is based on DSpace, following the [DC-HTML](https://www.dublincore.org/specifications/dublin-core/dc-html/2008-08-04/) conventions.
|
|
|
|
## Open Graph Protocol
|
|
|
|
[Open Graph](https://opengraphprotocol.org/) provides basic metadata in a open standard used by social media sites to generate representations of links shared on the platform.
|
|
Open Graph was established by Facebook, but can be read by other platforms.
|
|
|
|
OG meta tags are automatically added to every page and are not configurable.
|
|
They provide an authoritative title, description, and image that can be used to represent a link to the page.
|
|
The OG image will be the item image/thumb in the case of item pages, or the site featured image for all other pages.
|
|
For example:
|
|
|
|
`<meta property="og:title" content="{{ page.title | escape }}" />`
|
|
|
|
## Schema.org
|
|
|
|
Schema is a standard designed to provide structured semantic markup for search engines to better understand content of web pages.
|
|
The concepts described apply to a generalized web landscape, centered mostly around commercial sites, and don't necessarily follow the logic and structure of library-based metadata or digital collections.
|
|
However, it is useful to provide the markup to drive better representations of the data in search results.
|
|
See [Full Schema hierarchy](https://schema.org/docs/full.html), or [Google Guide to Structure Data](https://developers.google.com/search/docs/guides/intro-structured-data).
|
|
|
|
Keep in mind that Schema is an open standard, however, Google is the biggest consumer, so information found in Google's [Developer Docs](https://developers.google.com/) is potentially more pragmatically useful (e.g. Google highly recommends using JSON-LD vs. Schema suggesting microdata).
|
|
Markup can be tested using Google's [Structured Data Testing Tool](https://search.google.com/structured-data/testing-tool).
|
|
|
|
The Schema markup is different on a variety of page types:
|
|
|
|
### Item pages
|
|
|
|
Item pages have in depth Schema markup in JSON-LD format driven by the object metadata.
|
|
Schema elements are driven by the "schema_map" column of config-metadata.csv.
|
|
Each item page is given the basic type of `CreativeWork`, thus metadata fields can be mapped to any of the properties listed on the [CreativeWork documentation](https://schema.org/CreativeWork).
|
|
Copy the exact property name, as this value will be turned into schema JSON-LD markup.
|
|
If the "schema_map" column is empty, only the automatically generated markup will be added.
|
|
|
|
Suggested field mappings include:
|
|
|
|
- `headline` (i.e. the title)
|
|
- `creator`
|
|
- `dateCreated`
|
|
- `description`
|
|
- `keywords`
|
|
- `contentLocation`
|
|
- `encodingFormat` (MIME type, should = format field of CollectionBuilder items)
|
|
- `license` (should only be used with a standardized rights URL)
|
|
|
|
Additionally, the Schema type, `isPartOf` (the collection), `image` (url), `thumbnailUrl` (url), and page `url` will be added automatically.
|
|
|
|
Note: in the future, our base item type may move to `ArchiveComponent` when this spec is fully integrated into the standard, https://schema.org/ArchiveComponent .
|
|
An alternative approach would be to use `ItemPage`, https://schema.org/ItemPage to describe the object pages, although this seems less direct.
|
|
|
|
Item pages are also marked up with Schema [BreadcrumbList](https://schema.org/BreadcrumbList) to represent their nesting in the site, which may be [represented in search results](https://developers.google.com/search/docs/data-types/breadcrumb).
|
|
|
|
### Data page
|
|
|
|
The Data page includes Schema markup in JSON-LD representing the various data derivatives that can be downloaded (implemented in _includes/data-download-modal.html which is included by the data layout).
|
|
See [Google dataset docs](https://developers.google.com/search/docs/data-types/dataset) and [Schema Dataset](https://schema.org/Dataset) for details behind this implementation.
|
|
|
|
The full metadata download in csv and json are automatically added.
|
|
A metadata facets json file is added if fields are set in theme "metadata-facets-fields".
|
|
Additional datasets described are selected based on what pages are in the config-nav, following the same logic used to select which data download buttons are shown to users.
|
|
If the config-nav contains the following "stub", the following data files will be added to the markup:
|
|
|
|
- "subject", subjects.csv, json
|
|
- "location", locations.csv, json
|
|
- "map", geodata.json
|
|
- "timeline", timelinejs.json
|
|
|
|
This may not be accurate for all use cases.
|
|
An easy way to manually set the downloads, is to create a list based on the stub values shown above, and edit the "stubs" assigned on the data/ layout.
|
|
For example, if I want to show all data downloads, even though I don't have the pages in the navigation or have named them something different, edit the "assign stubs" line on data/ like this:
|
|
|
|
`{%- assign stubs = "subject;map;location;timeline" -%}`
|
|
|
|
Also check docs/data.md for more information.
|
|
|
|
### Content pages
|
|
|
|
Other pages in the site receive more basic markup from the head/page-meta.html include following the [WebPage schema type](https://schema.org/WebPage).
|