CLI Recommendation for Syntax Highlighting?

[coolaj86]

I see that there's no built-in highlighting, just the annotation.

echo '# JavaScript:

```js
function add(a, b) {
    return a + b;
}
```
' | comrak --gfm

<h1><a href="#javascript" aria-hidden="true" class="anchor" id="javascript"></a>JavaScript:</h1>
<pre lang="js"><code>function add(a, b) {
    return a + b;
}
</code></pre>

This makes makes sense because that's not really part of markdown per se and it would probably bring in an undesirable number of dependencies.

I'm wondering if you have a recommendation of a tool (rust, go, or otherwise) that is as easy to install and use as comrak (i.e. not ruby, node, or python with all their dependencies) that I could put in the next | to complete the output.

Thoughts?

I understand that this is outside of the scope of comrak itself, but I believe it's worth noting at least hear in the issues since these are tools that would commonly go together.

[kivikakk]

I'm not sure an appropriate tool exists, I'm afraid. Most library users will use syntect or include something like Highlight.js to do the highlighting on the client side.

We could add the functionality behind a feature flag and make it only default for the binary; I would accept a PR that adds this functionality with syntect!

[coolaj86]

Just doing a little research to help this along:

• find_syntax_by_extension and find_syntax_by_name may be useful for fenced codeblocks
• Possibly relevant examples:
  • https://docs.rs/syntect/4.4.0/syntect/easy/struct.HighlightLines.html
  • https://docs.rs/syntect/4.4.0/syntect/html/fn.highlighted_html_for_string.html
  • https://github.com/trishume/syntect/blob/9c9f7f6631d527d24856ed1b27da90f84bf507ac/src/html.rs#L225

I'm not quite clear on what the list of names that need to be used are to match syntax. For example md, mkdn, and markdown might be "extensions" or "names"?

Also, I'm not clear on how it would be keeping state between lines to know how deeply nested a function or some such would be.

Recently I've found myself in this issue as well, I would like to use both comrak and syntect, but unfortunately I haven't found a way to make them work together.

I had two solutions in my mind:

1. Make it possible for comrak to accept plugins for syntax highlighting, and then the user could define their own adapter for using the syntax highlighter library of their choice. I think, this would be an elegant solution.
2. Make it possible in comrak to disable parsing individual blocks. E.g. provide an options flag to disable parsing code blocks, so the fenced code blocks would remain intact, and then a different parser library could have another round with the input and parse what's left unparsed (in this case, the code blocks).

I could probably make a pull request in the coming weeks if any of the proposed solutions is acceptable.

UPDATE: Actually, these solutions would be more suitable for using comrak as a dependency, not in the CLI interface. But as it was discussed above, a default adapter could be made for syntect, and a corresponding CLI flag.

[kivikakk]

I think solution 1 sounds good to me. I'd be happy to accept such a PR.

I have created an experimental implementation that seems to be working pretty well, however, I cannot push my branch due to permission (?) issues.

remote: Permission to kivikakk/comrak.git denied to helmet91.
fatal: unable to access 'https://github.com/kivikakk/comrak.git/': The requested URL returned error: 403

This would be my first time contributing to a real open-source project here on GitHub. Could you please help me with figuring out what went wrong? I'm not sure if this is a repository configuration, or just I've messed up something.

[kivikakk]

Ah, yes — you will need to fork comrak into your own account, and push your branch to your fork. Then, you can open a Pull Request.

To get started, click the Fork button at the top-right corner of the comrak repository home page:

This should produce a repository that looks like https://github.com/helmet91/comrak.

Then, add your fork as a remote to your local clone. The default remote name when you clone a repository is origin, so I often call the remote kivikakk to reflect that it's a fork in my account when I'm working on others' projects.

If you were to do the same and call yours helmet91, you could do so like this:

$ git remote -v
origin  git@github.com:kivikakk/comrak.git (fetch)
origin  git@github.com:kivikakk/comrak.git (push)
$ git remote add helmet91 https://github.com/helmet91/comrak.git
$ git remote -v
helmet91        https://github.com/helmet91/comrak.git (fetch)
helmet91        https://github.com/helmet91/comrak.git (push)
origin  git@github.com:kivikakk/comrak.git (fetch)
origin  git@github.com:kivikakk/comrak.git (push)
$

Now, push your branch to your fork. We use -u (--set-upstream) so that git saves the remote information against the branch in .git/config, in case you want to push more commits later.

$ git push -u helmet91 YOUR_BRANCH_NAME_HERE

Make sure to specify the branch name that you've committed to locally. (It's okay if it's the default branch name, main, too. Pull Requests can be from and to any branch.)

The output from the server should include a handy URL you can click on to open the Pull Request. Good luck!

[kivikakk]

By the way, here's a guide on this workflow: https://jarv.is/notes/how-to-pull-request-fork-github/

It's a little bit different because they assume you start out by cloning your fork, and then add the upstream remote. Git is extremely flexible and it makes no big difference either way; you can very easily switch the names of things and have many remotes in the one (local) clone. At its core, a git repository is just an object database, and the commits do not record themselves which remote they came from.

Thank you for the detailed explanation!

[kivikakk]

The wonderful syntect integration by @helmet91 in #194 has been merged; I will update and close this issue once a new release is made which includes this, hopefully this week!

[kivikakk]

That's done. Thank you so much, all!

https://github.com/kivikakk/comrak/releases/tag/0.12.0