Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
251 lines (159 loc) · 9.33 KB

CONTRIBUTING.md

File metadata and controls

251 lines (159 loc) · 9.33 KB

Contributing to Quarkdown

Thanks for interest in contributing to Quarkdown, the Markdown-based typesetting system, and its ecosystem!

All types of contributions are encouraged and valued. Please make sure to read the relevant section before making your contribution, as it will make it easier for maintainers to handle it.

If you like the project, but don't have time to contribute, that's totally fine! You can still support us and show your appreciation by doing any of the following:

  • Star 🌟 the project.
  • Post the project on social media.
  • Mention the project to others.

Table of Contents

Questions

Before you ask a question, it is best to search for existing Issues or Discussions that might help you.

If you then still feel the need to ask a question and need clarification, we recommend the following:

  • Open a Discussion or Issue, depending on what you feel is more appropriate for your question.
  • Provide as much context as you can about what you're running into.
  • Provide project version, along with JVM version and OS if relevant.

We will then take care of the issue as soon as possible.

Contributing via issues

Legal Notice

When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.

Reporting Bugs

Before submitting a bug report

A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible.

  • Make sure that you are using the latest version.
  • Determine if your bug is really a bug and not an error on your side.
  • Check if there is not already an issue for your bug in Issues.

Submitting

Open an Issue with a clear and descriptive title. The body should contain the following information:

  • Your input
  • The output or stack trace
  • JVM version
  • Operating system
  • Can you reliably reproduce the issue? And can you also reproduce it with older versions?

Suggesting Enhancements

Before submitting an enhancement

  • Make sure that you are using the latest version.
  • Check the wiki and documentation carefully to check if the functionality is already present.
  • Check Issues to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
  • Find out whether your idea fits with the scope and aims of the project.

Submitting

Open an Issue with a clear and descriptive title. The body should contain the following information:

  • Provide a step-by-step description of the suggested enhancement in as many details as possible.
  • Describe the current behavior and explain which behavior you expected to see instead. At this point you can also tell which alternatives do not work for you.
  • Explain why this enhancement would be useful.

Contributing via PR

Your first contribution

Important

Please open a PR only after opening an Issue for the change you want to make, so that maintainers can give you feedback on whether your contribution is likely to be accepted and how it should be implemented.

The following list shows contributions that are highly welcome, in order of importance:

  1. Issues labeled with good first issue or help wanted. These issues are usually easier to solve and are a good starting point for new contributors.

  2. Improve the documentation of the standard library, which will be shown in the auto-generated documentation.
    To have a preview of the generated documentation, you can run gradlew quarkdocGenerate

  3. Improve performance of the pipeline.

  4. Add new functions to the standard library. It's suggested to open an enhancement suggestion first.

  5. Add new themes. Please ensure your theme looks correctly on all document types (plain, paged, slides, docs) on the Mock document and Quarkdown's wiki.

Understanding the architecture

The architecture behind Quarkdown's core is explained in the wiki's Pipeline.

Lib directory

A Quarkdown installation ships a lib/ directory next to the JARs, containing every resource the runtime needs that does not live on the classpath:

<install>/
  bin/quarkdown
  lib/
    qd/        # bundled .qd library files (from quarkdown-libs)
    html/      # HTML rendering resources (navigable at runtime via InstallLayout.Html)
      lib/     # third-party JS/CSS libraries
        bootstrap-icons/
        highlight.js/
        katex/
        mermaid/
        ...
      script/  # Quarkdown runtime
        quarkdown.min.js
        quarkdown.min.js.map
      theme/   # compiled CSS themes
        global.css
        layout/<name>/
        color/<name>/
        locale/<tag>/

The shape is defined once by installLibLayout in the root build.gradle.kts and reused by two consumers:

  • installDist / distZip for the packaged installation (via manual download and package managers). Here, the lib/ alongside bin/ contains also the JAR files.
  • assembleDevLib is a task that materializes the same layout at <rootProject>/build/dev-lib/, without needing a full installDist run. This synthetic lib directory exists so that ./gradlew run, tests, and other run configurations can resolve a real install-shaped lib/ at runtime, picking up the offline bundle and the standard library exactly as a packaged installation would.

HTML offline asset bundling

Rendered HTML documents are fully offline: every third-party asset (fonts, JS libraries, CSS, code highlighting, themes) is bundled into the Quarkdown installation and copied next to each generated document.

The bundling flow lives in quarkdown-html/build.gradle.kts. At render time, ThirdPartyPostRendererResource and ThemePostRendererResource walk the install's lib/html/ directory and copy the relevant assets next to the generated document.

Tooling

If you're using IntelliJ IDEA, you can import run configurations from the .run directory.

Building

The project uses Gradle as its build system. To build the project, always run:

./gradlew installDist

Warning

Avoid ./gradlew build, always use installDist or distZip instead.

Testing

To run the full test suite:

./gradlew test

You can also run tests for a specific module:

./gradlew :quarkdown-core:test
./gradlew :quarkdown-html:test

End-to-end tests are heavy and aren't included in :test. They can be run with:

./gradlew :quarkdown-html:e2eTest

Note that all tests are automatically run on every PR.

Running the CLI

You can run the Quarkdown CLI directly via Gradle, without needing to build the project first:

./gradlew run --args="c <file.qd> [options]"

Documentation

  • To compile the wiki, run either of the following commands from the docs directory:

    • quarkdown c main.qd --clean --strict --allow all
    • ./gradlew run --args="c main.qd --clean --strict --allow all"

  • To generate Quarkdoc documentation only for the standard library:

    ./gradlew quarkdocGenerate

  • To generate Quarkdoc documentation for the whole project:

    ./gradlew quarkdocGenerateAll

Styleguides

Kotlin code style

Quarkdown uses ktlint to ensure a consistent codestyle is kept across the whole project.

Upon opening a PR, ./gradlew ktlintCheck is automatically run, and the checks must pass before the PR can be merged. You can also run ./gradlew ktlintFormat to automatically fix any formatting issues in your code.

Commit messages

Please ensure your commit messages use the imperative tense and following the conventional commits specification, so that they are clear and consistent across the project.

Attribution

This file was inspired by contributing.md.