https://github.com/cthoyt/catalog

Made with Manubot catalog (please add your manuscript!!)

https://github.com/cthoyt/catalog

Repository

Made with Manubot catalog (please add your manuscript!!)

https://github.com/cthoyt/catalog/blob/master/

# Manubot Catalog

[![Travis CI Build Status](https://travis-ci.com/manubot/catalog.svg?branch=master)](https://travis-ci.com/manubot/catalog)

Manubot is a workflow and set of tools for the next generation of scholarly publishing.
Learn more at .

This repository stores a catalog of manuscripts that were made using Manubot.
These manuscripts are displayed at .
The `catalog.json` file produced by this codebase is available at `https://manubot.github.io/catalog/catalog.json`.

## Contributing

We encourage anyone to add manuscripts to the catalog.
In-progress manuscripts are acceptable.
Basically, any manuscript that has a substantial amount of content that is not part of [Rootstock](https://manubot.github.io/rootstock/) is of interest.

GitHub repositories containing Manubot manuscripts can be found with [this search](https://github.com/search?o=desc&q=manubot+in%3Areadme&s=updated&type=Repositories).

To add a manuscript to the catalog, add a record in [`catalog.yml`](catalog.yml).
`catalog.yml` is a YAML formatted file.
An example manuscript with documentation comments is below:

```yaml
- repo_url: https://github.com/greenelab/deep-review  # URL to GitHub repository with Manuscript source code
  html_url: https://greenelab.github.io/deep-review/  # URL for Manubot HTML output (usually hosted by GitHub Pages)
  thumbnail_url: https://url_for_image.png  # optional: square image to represent the manuscript. Overrides thumbnail set by manuscript.
  preprint_citation: doi:10.1101/142760  # optional: Manubot-style citation for a preprint corresponding to the manuscript
  journal_citation: doi:10.1098/rsif.2017.0387  # optional: Manubot-style citation for a published article corresponding to the manuscript
```

For more information on how to create citations for `preprint_citation` and `journal_citation`, see Manubot's citation-by-identifier [documentation here](https://github.com/manubot/rootstock/blob/master/USAGE.md#citations).
Specifying `thumbnail_url` overrides the thumbnail image detected from the metadata of `html_url`.
Therefore, setting `thumbnail_url` is only neccessary if the manuscript does not supply a thumbnail image or if the catalog should use a different image.

## Thumbnail Guidelines

Follow these guidelines when creating your thumbnail to help us maintain a beautiful, consistent, and streamlined catalog.
They are listed roughly in order of most strict to least strict.

*Click on the arrows/triangles to show more details about the guideline.*



Size dimensions to 1000  1000 pixels


Provide an image exactly 1000 pixels wide by 1000 pixels high.
Why do we ask for such a large image when the thumbnails of the papers appear so small in the catalog?

1. Web browsers can use the extra pixels to display a crisper image when zoomed in (especially important on high dpi displays).
2. The layout/design of the catalog is subject to change, which may show the thumbnails at larger sizes.
3. In general, we want to future-proof the catalog against increasing image resolution standards, and for Manubot's own changing needs.





Use PNG format


Provide your image as a `.png` file.
This avoids unsightly artifacts produced by other common image formats while still keeping file size to a minimum.





Select a striking image


Select a portion of your manuscript that is interesting and unique.
Your thumbnail is not expected to accurately capture or explain what your manuscript is about.
The purpose of the thumbnail is to visually distinguish your paper from other papers, so that readers can easily remember and quickly identify it among many others.
As such, the first preference is for a unique, colorful figure, without its caption.
If your manuscript has no figures, use an interesting-looking table, code block, or set of equations.
If your manuscript has none of those, use any other section that looks unique in some way; more than just a paragraph of black text.
If your manuscript is all just plain text, don't provide a thumbnail at all; a placeholder thumbnail will be used automatically.





Don't stretch


Don't distort the original aspect ratio of your image; not even a little.
It looks bad and is very noticeable.
Asymmetrical horizontal and vertical whitespace is much preferable to a stretched image.
If you are struggling to meet the dimension requirement, refer to the guidelines on cropping.





Don't scale


You should always create, save, and maintain your figures in vector format where possible.
This allows the image to be scaled to any size without loss of quality.
If your thumbnail source is a vector image, scale it to the required dimensions *before* converting/rendering it to `.png`.
Do not, for example, render your vector image to a 800800 `.png` and then scale it up to 10001000.
If your thumbnail has to be a raster image, it still must meet the dimension requirements above, and may be rejected by the catalog maintainers if it is noticeably up-scaled.





Use a solid background


If your image has any transparent/translucent areas, place a background behind it.
Solid backgrounds are strongly preferred.
White is the first preference, but if it is necessary to use a different color to achieve adequate contrast, we ask that you follow the [Manubot style guidelines](https://github.com/manubot/resources/blob/master/brand/readme.md#style-guidelines) to the best of your ability.





Don't include paragraph text or captions


Text, especially plain black text, serves little to no purpose in a thumbnail.
Thumbnails are meant to be quick visual identifiers, not snippets of detailed content.
Don't include text in your thumbnail, unless it is baked into the figure itself (not its caption), or unless it is necessary per the "striking image" guideline above.





Frame/crop nicely


Cropping an image nicely is more of an artform than you might think.
As such, it's hard to specify a set of hard/quantifiable rules about what looks good.
If you're familiar with [frame composition](https://en.wikipedia.org/wiki/Composition_(visual_arts)) from art/photography/cinematography, the same techniques can be applied here.
In addition, here are some general guidelines to follow:



Choose a good aspect ratio


Since our dimension requirements are a square, figures that are square or close to square will look the best.
Figures with an aspect ratio greater than 3:1 (width:height or height:width) should be avoided.
For example, a figure that is more than three times taller than it is wide might not be the best choice for a thumbnail.



Center horizontally and vertically


Centering an image horizontally and vertically tends to look the best.
But be careful: sometimes making the space on either side exactly the same actually doesn't look centered to the human eye.
Consider a typical play button icon, a rightward-pointing triangle.
Its center of mass is slightly to the left, and needs to be moved slightly right of true-center to look naturally-centered.
Take into account the "center of mass" of your figure.



Use ~50px of padding


Where it is possible to contain your whole figure in the bounds of the image, keep about 50px of space between the content of the figure and each boundary of the image.
If your figure has to extend beyond the vertical boundaries of the image, leave this much horizontal padding, and vice versa.
In general, on any side that you're cutting through white-space, leave this much padding.



Cut through white-space


Don't cut through text or other significant objects at the borders of your image.
If it is absolutely necessary to do so, choose the cut point with care.
Cutting through the center or quarter-waypoint of an object looks better than -- for example -- leaving a stray, unintentional-looking 3 pixels of it protruding into the image.
If a small protrusion like that is absolutely necessary, it's okay to simply white it out and make it blank space.







Use good contrast


Your thumbnail may be viewed at different sizes and on different screens.
It is important that anyone can see clearly defined shapes in your image, even at a small size.
Make sure the key edges and outlines of your objects are sharp and readable.
Do not use colors that are close together.
Avoid hard to read combinations like white and yellow.





Don't show plugins (irrelevant if submitting a figure directly)


Don't show Manubot or third party plugins in your thumbnail.
The purpose of the thumbnail is to represent your particular paper, not to showcase features of Manubot (there are other places for that).
In particular, be mindful to remove the Hypothesis side toolbar, Hypothesis highlights, the table of contents panel, and any open tooltips.



Don't show theme decorations (irrelevant if submitting a figure directly)


Some Manubot themes show a subtle page border and shadow, meant to represent an actual sheet of paper.
Don't include these in your thumbnails, or any other theme decoration that will add clutter to the image in its final context.
For example, our catalog already adds a shadow around the thumbnails, and it would look bad to have another shadow within the image itself.
These types of effects are intended to be "sugar"/embellishment for the html version of manuscripts only.
They're not considered core to the content and functionality of the paper, and thus don't belong in a thumbnail.
They are also more likely to change as web design trends change.
In general, if a piece of styling is stripped away when printing your manuscript, don't include it in your thumbnail.



Use default theme, without modifications (irrelevant if submitting a figure directly)


To keep the catalog thumbnails consistent, we prefer that you use the default Manubot theme when creating your thumbnail.
We also strongly prefer you make no modifications to the theme, to ensure that sizing and spacing of elements on the page are all in-line with best-practices of graphic design.



_**When in doubt, look at the other thumbnails and model yours after them.**_

Owner

GitHub Events