Skip to content

Latest commit

 

History

History
103 lines (85 loc) · 4.79 KB

CONTRIBUTING.md

File metadata and controls

103 lines (85 loc) · 4.79 KB
Raw

Contributing

Thanks for considering to contribute!

GitHub's API for Discussions is currently only available through the GraphQL API, which currently requires authentication for all requests. With the way giscus works, you'll need to create a GitHub App in order to get it running on your machine. Follow the self-hosting guide to get it running.

Setup

To contribute to giscus, follow these steps:

  1. Fork the repository to your GitHub account.
  2. Clone the repository to your device (or use something like Codespaces).
  3. Create a new branch in the repository.
  4. Make your modifications.
  5. Commit your modifications and push the branch.
  6. Create a PR from the branch in your fork to giscus' main branch.

This project is built with Next.js and yarn as the package manager. Here are some commands that you can use:

  • yarn: install dependencies
  • yarn dev: compile and hot-reload for development
  • yarn build: compile and minify for production
  • yarn lint: lint and fix files
  • yarn start: serve the compiled build in production mode

Creating new themes

If you want to submit your custom theme to giscus, create a new file in styles/themes. The file name (without .css) will be the theme's key. You can use the other theme files as reference (see custom_example.css). Once you've added the theme file, add the key and name to Theme in lib/variables.ts to register it. Please also update the config.json in each localization in the locales directory to include a theme=your_theme_key key.

If you want to customize the syntax themes, you can change the CSS variables that start with the --color-prettylights-syntax- prefix. See the custom_example.css file for more details.

To support both light and dark mode based on the user's system preferences, you can use the @media (prefers-color-scheme: dark) query. For more details, see the preferred_color_scheme theme file.

Several classes prefixed with gsc- are used in the HTML generated by giscus. You can take advantage of this to further customize your theme. Note that the classes and HTML structure are subject to change, as updates to giscus may require modifications to the HTML. You'll need to make sure that your theme is up-to-date.

If you want to use a custom theme without submitting it to giscus, you can do so by using a custom theme URL. Note that you cannot @import a syntax theme and must inline it in your CSS. That said, if you create a nice theme, I'd appreciate it if you create a PR instead so others can use it easily.

Adding localizations

If your language is not yet supported by giscus, please contribute a localization! Follow these steps to add a new localization:

  1. Copy one of the directories in locales and rename the new directory into your language's code.
  2. Open common.json and config.json inside the directory.
  3. Start translating the strings. Make sure to follow your language's plural rules for translation keys with an object as the value (e.g. those that require {{ count }}).
  4. Copy one of the README files and name it README.[code].md, e.g. README.id.md and translate the content. Add your language to the bottom of the new README and all the existing READMEs.
  5. Edit i18n.tsx and update the following variables:
    • availableLanguages: include your language code and name.
    • dateFormatters, shortDateFormatters, shortDateYearFormatters, and relativeTimeFormatters: include new objects with your language code, following the existing languages.
  6. Edit i18n.json and include your language.
  7. In all of the aforementioned files, make sure that the language list is sorted by the language code.
  8. Create a PR with your localization updates.