search

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you
https://orchid.run
GNU General Public License v3.0
518 stars 53 forks source link

Feature request (with implementation provided): code from github via gist-it #390

Closed DanySK closed 3 years ago

DanySK commented 3 years ago

Code should never be duplicated, yet often in the documentation we need to show snippets from some other place. AFAIK, the current Orchid way is just to copy paste within a Markdown code environment.

However, the great gist-it service allows for importing code snippets into pages directly from github (not gists, true code).

I prepared a tag that does the job for a website of mine, and I believe it could be of use to others, so I propose its integration into Orchid.

Use example:

{% gistit
    owner = "AlchemistSimulator"
    repository = "alchemist-primer"
    file = "build.gradle.kts"
    slice = "8:11"
%}

Pebble template: https://github.com/AlchemistSimulator/Alchemist/blob/da66b3667f84ce2bf07cf845602feb4ee2bd97ff/src/orchid/resources/templates/tags/gistit.peb#L1-L11 Kotlin tag implementation: https://github.com/AlchemistSimulator/Alchemist/blob/da66b3667f84ce2bf07cf845602feb4ee2bd97ff/src/orchid/kotlin/it/unibo/alchemist/orchid/EmbedCode.kt#L1-L50

Defaults of course can be changed to some example code of your like.

cjbrooks12 commented 3 years ago

This sounds like a great addition, I'd gladly accept a PR for it! I should be able to get it merged relatively soon, but it will likely take a while for me to get it actually released, as there are a number of things that I need to update first to get Orchid on MavenCentral

DanySK commented 3 years ago

Is there a guide for developers? Which sub-project should I target?

cjbrooks12 commented 3 years ago

There's a CONTRIBUTING.md with some basics on the project structure and building/running locally. This tag could go in the WritersBlocks module, which is the catch-all for tags and other things that don't really fit in any of the other modules.

More practically, the Orchid repo is overall a pretty normal Gradle JVM project. You can open it and run tests in IntelliJ IDEA as you would any other Java/Kotlin app, using the expected directory structure. Please include at least 1 test case with the PR. You can follow the tests for other tags in that module for an example of how to get them set up and properly testing, and there's full documentation for the Orchid testing APIs available as well.

DanySK commented 3 years ago

@cjbrooks12 pull request opened; see #399.

By the way, component loading could be automated by loading subtypes dynamically through Classgraph.