Librarian Contribution Guide

Last updated on January 6, 2025

Guide

Librarian Contribution Guide

Ways to Contribute

We are currently looking for contributions in the following areas:

• API Documentation: Help us improve the API documentation by adding new pages or updating existing content.
• API Guides: Share your knowledge by writing guides on how to use the Hardcover API.
• Bug Fixes: Help us fix bugs in the documentation site.
• Reporting Issues: Report any issues you encounter with the documentation site. Create Issue
• Feature Requests: Share your ideas for new features or improvements to the documentation site. Suggest Feature
• Librarian Guides: Share your expertise by writing guides on how to use the Librarian tools.

Finding Something to Work On

You can find issues to work on by looking at the Issues Board on GitHub or by joining the Hardcover Discord and asking for suggestions in the #API or #librarians channels.

Being a Good Contributor

When contributing to Hardcover, please follow these guidelines:

• Be respectful of others and their contributions.
• Be open to feedback and willing to make changes based on feedback.
• Be patient and understanding of the time it takes to review and merge contributions.
• Be clear and concise in your contributions.
• Be willing to help others and answer questions.
• Be willing to work with others to improve the documentation site.
• Be open to learning and growing as a contributor.
• Be willing to follow the contribution processes.
• Be willing to accept that not all contributions will be accepted.

How do I add a new page or update an existing page?

Adding a New Page

1. Navigate to the Hardcover Docs GitHub
2. Navigate to the src/content/docs/ directory.
3. Navigate to the appropriate subdirectory for the page you want to add.
4. Click the “Add file” button near the top right of the file list.
5. Click the “Create new file” option.
6. In the editor that opens, give the new file a meaningful name ending in .mdx, see the existing files for examples.
7. Add the frontmatter to the new page using the template below.
8. Provide the content for the new page using Markdown or MDX syntax.
9. Preview your changes for formatting and accuracy.
10. Click the “Commit changes…” button at the top of the page.
11. In the dialog that opens, provide a title and description for your changes.
12. Ensure the “Create a new branch for this commit and start a pull request” option is selected.
13. Give your branch a short, descriptive name.
14. Click the “Propose changes” button to save your changes.
15. Notify the Hardcover team, namely @revelry in the Hardcover Discord that you have submitted a pull request.
16. Wait for feedback and review from the Hardcover team.
17. Make any requested changes.
18. Once your pull request is approved, it will be merged into the main branch.
19. Celebrate your contribution!
20. Continue contributing to Hardcover!

Editing an Existing Page

1. Using the UI navigate to the page, you want to edit.
2. Click the “Edit page” button near the bottom of the content.
3. In the GitHub page that opens, click the pencil icon on the top right of the file to start editing.
4. Make your changes in the editor using Markdown or MDX syntax.
5. Update the frontmatter as needed using the template below, make sure to update the lastUpdated field.
6. Preview your changes for formatting and accuracy.
7. Click the “Commit changes…” button at the top of the page.
8. In the dialog that opens, provide a title and description for your changes.
9. Ensure the “Create a new branch for this commit and start a pull request” option is selected.
10. Give your branch a short, descriptive name.
11. Click the “Propose changes” button to save your changes.
12. Notify the Hardcover team, namely @revelry in the Hardcover Discord that you have submitted a pull request.
13. Wait for feedback and review from the Hardcover team.
14. Make any requested changes.
15. Once your pull request is approved, it will be merged into the main branch.
16. Celebrate your contribution!
17. Continue contributing to Hardcover!

Adding Images

Currently, images have to be added as a separate pull request. To add an image:

1. Navigate to the Hardcover Docs Github
2. Navigate to the public/images/ directory.
3. Navigate to the appropriate subdirectory api or librarians depending on where the image will be used.
4. Click the “Add file” button near the top right of the file list.
5. Click the “Upload files” option.
6. Drag and drop the image file(s) into the upload area.
7. In the Commit changes section, provide a title and description for your changes.
8. Ensure the “Create a new branch for this commit and start a pull request” option is selected.
9. Give your branch a short, descriptive name.
10. Click the “Propose changes” button to save your changes.
11. Notify the Hardcover team, namely @revelry in the Hardcover Discord that you have submitted a pull request.
12. Wait for feedback and review from the Hardcover team.
13. Make any requested changes.
14. Once your pull request is approved, it will be merged into the main branch.
15. After the image is merged, follow the steps in the Editing an Existing Page section to add the image to and reference it using the relative path: /images/subdirectory/your-image.png.

<img src="/images/librarians/long-title-example.png" alt="Example of a long title on Hardcover" />

Page Frontmatter

Field	Description	Required
title	String containing the title of the page	Yes
category	String of the category the page should be included in guide or reference	Yes
layout	relative path to /src/layouts/documentation.astro	Yes
description	String containing the descriptive text to use in HTML meta tags	Recommended
lastUpdated	String in the format YYYY-MM-DD HH:MM:SS	Recommended
draft	Boolean value determining whether the page should be hidden from the production site	No
slug	String containing the URL slug for the page	No
tableOfContents	Boolean value determining whether a table of contents should be generated	No
template	doc or splash default is doc. splash is a wider layout without the normal sidebars	No
hero	See Starlight - Frontmatter HeroConfig for more information	No
banner	See Starlight - Frontmatter Banner for more information	No
prev	Boolean value determining whether a previous button should be shown. See Starlight - Frontmatter Prev for more information	No
next	Boolean value determining whether a next button should be shown. See Starlight - Frontmatter Next for more information	No
sidebar	Control how the page is displayed in the sidebar. See Starlight - Frontmatter Sidebar for more information	No

Example Frontmatter

---
title: Getting Started with the API
description: Get started with the Hardcover GraphQL API.
category: guide
lastUpdated: 2025-02-01 17:03:00
layout: ../../layouts/documentation.astro
---

Translation Support

While we currently only support English, we are open to adding translations in the future. If you are interested in contributing translations, please reach out to the Hardcover team in the #API or #librarians channels on the Hardcover Discord.

Support Resources

Finding Help on Discord

Connect with us on Discord