Skip to content

Update language-highlight.md #1251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 27, 2020
Merged

Update language-highlight.md #1251

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
138b989
Update language-highlight.md
trusktr Jun 27, 2020
9f3cf1e
Update language-highlight.md
sy-records Jun 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/language-highlight.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,25 @@
<script src="//cdn.jsdelivr.net/npm/prismjs/components/prism-php.min.js"></script>
```

To use the new languages, make sure the code block label matches the part after `prism-` in the file name. FOr example, for `prism-bash.js` write a code block labeled with `bash` like this:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor typo: "FOr" should be "For" (lower-case "O").


````
```bash
echo "hello"
```
````

?> Note that with GitHub-flavored markdown, `sh` and `bash` are effectively aliases of each other, but this is not the case with Prism. So using `sh` will not enable `bash` syntax in this case.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is confusing for a few reasons:

  1. GitHub-flavored markdown doesn't handle syntax highlighting (see spec). I think you're referring to how GitHub handles markdown.
  2. Docsify supports GitHub-flavored markdown (see the Supported Markdown specifications for marked)
  3. Prism's source lists sh as an alias for bash.
  4. Prism's docs list shell as an alias for bash (and sh is an alias for shell).

I suggest we just delete the ?> Note... section.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

GitHub-flavored markdown doesn't handle syntax highlighting

Maybe I should say "Markdown on GitHub".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prism's source lists sh as an alias for bash.

When I add prism-bash.js and use sh as the syntax it doesn't highlight. Same with shell. bash works though. Is it new? Does it work for you? Maybe I need an update.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was incorrect about sh being an alias for shell and bash in the Prism source (it was late 🤷 ). Prism simply associates sh as a file extension for bash scripts.

The difference between GitHub and Prism highlighting is:

  • Prism requires using the alias(es) listed in their docs. For Bash, Prism lists only bash and shell. I can confirm both bash and shell work as expected in docsify-themeable, while sh does not work:

    Screen Shot 2020-06-28 at 11 24 09 PM

  • GitHub (it appears) uses file extensions (like sh) in addition to the usual aliases. Notice how the same markdown from the screenshot above renders here on GitHub (specifically, the proper sh highlighting):

    # bash
echo "hello"
    # shell
echo "hello"
    # sh
echo "hello"

    To confirm this, I tried to find another file type that Prism associates an extension with but does not list as an alias. Batch has a file extension of bat in the source but only lists batch as an alias in the docs so this is a good match. Here's how batch and bat render on docsify-themeable:

    Screen Shot 2020-06-29 at 12 20 17 AM

    And here's how that above markdown renders here on GitHub:

    :: batch
@ECHO "HELLO"
    :: bat
@ECHO "HELLO"

Summary: Docsify uses Prism aliases only, GitHub uses language aliases and extensions.


For `prism-php.js`, it would be:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need two examples? If we want two, why not use one of the built-in languages (css, html, or js) and one that requires loading an additional language?


````
```php
function getAdder(int $x): int
{
return 123;
}
```
````

?> Check the [component files](https://github.com/PrismJS/prism/tree/gh-pages/components) list for more options.