Repository files navigation

This repository includes source code for theCDH-sponsored Lunaapahkiing Princeton Timetree (LPT) research project. It consists of a custom Hugo theme, with HTML and JSON templates, JavaScript, SCSS, and other assets. It is used withPrinceton-CDH/lenape-timetree-content to build theLunaapahkiing Princeton Timetree web application.

The timetree javascript code in v1.0.1 of this codebase wasreviewed byCole Crawford (Senior Software Engineer, Harvard Arts and Humanities Research Computing) andRaff Viglianti (Senior Research Software Developer, Maryland Institute for Technology in the Humanities) viaDHTech Community Code Review; review was faciliated byJulia Damerow (Lead Scientific Software Engineer, Arizona State University).

Note: this project was originally developed in a single git repository; in September 2023 the repository was split out to separate content and code to simplify maintenance and ownership. An archive of the original git repository with the combined history up to that point is available atPrinceton-CDH/lenape-timetree-archive.

The software for this project is licensed under theApache 2.0 License.

For instructions on editing site content, refer toCONTRIBUTING.Local setup is not required for content editing.

To set the site up locally for development or content editing,first follow theinstructions to install Hugo.You can check that Hugo is installed with:

hugo version

This should result in output something like this:

hugo v0.101.0+extended darwin/amd64 BuildDate=unknown

Make sure the version you installed is at least as new as the version shown in the Hugo badge at the top of the project readme (this file).

Once hugo is installed, you'll need to install the javascript dependencies that are used to compile the site's javascript and scss resource files. To check if you have node installed:

node --version

This should output a version string that is at least as new as the version shown in the node badge at the top of this file. To install dependencies, run npm in the project's root directory:

npm install

If the install completes without errors, you're ready to run the site locally.

To run a development server with auto-reload:

hugo server

You should see some debug output, followed by:

Web Server is available athttp://localhost:1313/ (bind address 127.0.0.1)Press Ctrl+C to stop

Open a web browser to the above address to see a local version of the site. When you make changes and save files locally, hugo will automatically refresh the page.

Anyone planning to do development on the site (i.e., contributing to javascript,scss, or templates), you need to install pre-commit hooks to automaticallyensure that code is consistently formatted. This step is not requiredfor anyone who is working on site content and not modifying code or templates.

Commit hooks are managed withpre-commit.To install, run:

pre-commit install

Current hooks includeBlack for python code formatting,isort for standardized python imports, andPrettier for javascript, css, markdown, and other supported file types.

Standardized code styles were instituted after some development was done on this project.To configuregit blame to ignore the styling commit, use the following:

git blame <FILE> --ignore-revs-file .git-blame-ignore-revs

Or configure git to always ignore the styling revision commit:

git config blame.ignoreRevsFile .git-blame-ignore-revs

To do development work on this theme with the corresponding content from this project, check out a copy of the timetree content repositoryPrinceton-CDH/lenape-timetree-content. Modify (but do not change) your go modules configuration to run from your local copy of the theme as follows:

go mod edit -replace github.com/Princeton-CDH/lenape-timetree=../lenape-timetree

And then runhugo from the content repository to build the site.

Thetimetree theme includes the following custom short codes.

A shortcode for including audio, which takessrc andcaption arguments, e.g.

{{<audio src="/audio/lunaapahkiing-pronunciation-mosko.mp3" caption="Listen to a pronunciation of *Lunaapahkiing* by Karen Mosko (Lunaape Language Teacher, Munsee-Delaware Nation)" >}}

view source

This is a customized version of Hugo's defaultfigure shortcode, adapted fromStartwords that rescales raster images using custom breakpoints and displays them with a caption.

It's highly recommended to usefigure rather than simple images via Markdown, so that images can be automatically sized and properly styled. Non-figure images may not display in a consistent manner.

You can optionally provide anattr to add an attribution to the caption, andattrlink will make the attribution a link pointing to the given URL. If you need extra control over the height of the image, you can pass any valid CSS measurement tomax-height, which will be applied via an inline style.

For assistive technology, analt is required to describe the image. Optionally, you can associate the image with another element containing a visually hidden long description usingdesc-id, which will be the value used foraria-describedby.

Simple example:

{{< figure src="images/duck.jpg" alt="Rubber duck sitting in a bathtub." >}}

Example use for a photograph with attribution:

{{< figure src="images/duck.jpg" alt="Rubber duck sitting in a bathtub." caption="Gerald relaxing in the bath." attr="Photo by me." attrlink="http://example.com/" >}}

Example use for a chart or graph, with long description:

{{< figure src="images/chart.svg" alt="Bar chart showing sales growth for Q1 2020." caption="Sales are improving for our industry." desc-id="chart-desc" >}}{{< wrap>}}Four different economic sectors are represented. The sector showing the most sales growth is the rubber duck industry, with growth approaching 25%.{{</ wrap >}}

• src, URL of the image in the figure.
• alt, text used by assistive technology to describe the content of the figure.
• caption, optional: descriptive text to be shown underneath the figure.
• attr, optional: attribution text to be shown underneath the figure.
• attrlink, optional: URL for makingattr text a hyperlink.
• desc-id, optional: html id of an element containing longer descriptive text.

view source

A shortcode for generating a project citation based on publication informationin the site and theme config files. Project citation can be generated with or without authors:

{{< project_citation noAuthors=true >}}{{< project_citation >}}

The citation uses the site title, and authors, version, publisher, publication date, and citation url from the site config. Authors should be listed in "Lastname, Firstname" format. For example:

authors:  -Lastname, First  -Lastname, First  -Lastname, Firstpublisher:Some grouppublication_date:2023citation_url:https://project.example.edu/

view source

This is a custom shortcode used to generate the branch legend in the opening panel of the timetree. Branches must be configured in site parameters.

view source