Raintale is a utility for publishing social media stories from groups of archived web pages (mementos). Raintale uses MementoEmbed to extract memento information and then publishes a story to the given storyteller, a static file or an online social media service.
Raintale accepts the following inputs:
- a file containing a list of memento URLs (URI-Ms) (required)
- a title for your story (required)
- the URL of the underlying collection (optional)
- the author, organization, or algorithm that generated the story (optional)
- the storyteller to use when generating the story (e.g., HTML, Twitter, Markdown)
- an output file for saving the story (if applicable)
- a credential file for the a social media service (if applicable)
- a template file allowing the user to format their story differently than the defaults (optional, and not supported by all storytellers)
Raintale supports the following storytellers:
- facebook - (EXPERIMENTAL) publishes a story as a Facebook thread, with titles, snippets, URLs, and memento-datetimes supplied by MementoEmbed
- html - the HTML that makes up a story, suitable for pasting into a web page or a blogging application such as Blogger
- twitter - publishes a story as a Twitter thread, with titles, URLs, memento-datetimes, and images supplied by MementoEmbed
- template - given input data and a template file, this storyteller generates a story formatted based on the template and saves it to the given output file, allowing the end user to format their own stories
- jekyll-html - writes output to Jekyll HTML file format, suitable for use with Jekyll and GitHub pages
- jekyll-markdown - writes output to Jekyll Markdown file format, suitable for use with Jekyll and GitHub pages
- markdown - writes output to the GitHub Flavored Markdown file format, suitable for pasting into GitHub
- mediawiki - writes output to this MediaWiki file format, suitable for pasting into MediaWiki pages
- video - (EXPERIMENTAL) creates an MP4 file containing the top images and sentences from the mementos in your story
Railtale also supports a number of presets for formatting a story for output to a specific file format:
- socialcard - provides a social card like those seen in social networking, may also provide an approximation, depending on file format (html, markdown, mediawiki, and jekyll storytellers)
- thumbnails3col - provides a 3 column layout containing thumbnails of the submitted mementos (HTML storyteller only)
- thumbnails4col - provides a 4 column layout containing thumbnails of the submitted mementos (HTML storyteller only)
Note that not all file formats support all presets.
Raintale uses docker-compose to load and execute all dependencies. To run raintale, do the following:
- Create a directory on your system
- Copy docker-compose.yml from this repository into that directory
- Open a terminal
docker-compose run raintale tellstory --helpto find the list of options
For example to create a raw HTML story suitable for pasting, type the following within that prompt:
docker-compose run raintale tellstory -i story-mementos.txt --storyteller html -o mystory.html --title "This is My Story Title" --generated-by "Me"
The output will be stored in
To create a twitter story, you will need to create a Twitter app. Log into Twitter from a web browser and visit https://developer.twitter.com/en/apps for more information. Once you have created an app, make a file named
twitter-credentials.yml, save it in the same directory, and fill it with the following content.
consumer_key: XXXXXX consumer_secret: XXXXXX access_token_key: XXXXXX access_token_secret: XXXXXX
XXXXXX values with the corresponding values as displayed on your Twitter app page.
Once that is done, type the following within the Docker prompt:
docker-compose run raintale tellstory -i story_mementos.txt --storyteller twitter --title "This is My Story Title" --generated-by "Me” -c twitter-credentials.yml
pip for build and installation. Clone this repository and type the following from the root of the source code:
pip install .
to build and install the version from the source code on your machine.
The future of Raintale
We are working on additional storytellers and presets. Storytellers must be either a file format or an online service that supports an API. The choice in storyteller is highly dependent upon the capabilities and terms of that online service's API.