Skip to content

Commit

Permalink
Updates to doc formatting, etc.
Browse files Browse the repository at this point in the history
  • Loading branch information
facelessuser committed Aug 13, 2023
1 parent 1809dfd commit a1b327a
Show file tree
Hide file tree
Showing 7 changed files with 192 additions and 163 deletions.
162 changes: 83 additions & 79 deletions docs/src/markdown/about/changes.md
Original file line number Diff line number Diff line change
@@ -1,173 +1,177 @@
# Changes

## 2.4.3

- **FIX**: Fix issues related to changing code block color schemes.

## 2.4.2

- **FIX**: Fix style so that PDF printing works in Chrome based browsers.
- **FIX**: Fix style so that PDF printing works in Chrome based browsers.

## 2.4.1

- **FIX**: Remove `desktop` lib as we should not have been using it under our current license.
- **FIX**: Fix a typo which prevents displaying useful error message.
- **FIX**: Remove `desktop` lib as we should not have been using it under our current license.
- **FIX**: Fix a typo which prevents displaying useful error message.

## 2.4.0

- **NEW**: Add `mermaid.js` support.
- **NEW**: Remove border from default styling of `markdown` and `github`.
- **NEW**: Exit out of `on_post_save` even quicker if no work is needed.
- **FIX**: `title` in YAML frontmatter should be handled case insensitively.
- **NEW**: Add `mermaid.js` support.
- **NEW**: Remove border from default styling of `markdown` and `github`.
- **NEW**: Exit out of `on_post_save` even quicker if no work is needed.
- **FIX**: `title` in YAML frontmatter should be handled case insensitively.

## 2.3.0

Some **breaking** changes! Please read:

- **NEW**: `pymdownx.superfences` no longer sources any settings from `markdown.extensions.codehilite` and instead uses
`pymdownx.highlight`. No need to specify `markdown.extensions.codehilite` in the default settings.
- **NEW**: Default `pygments_css` class is now set to `highlight` which is `pymdownx.highlight`'s default. If you are
using `pymdownx.superfences`, you use use `highlight`, if you are using `markdown.extensions.codehilite`, then you may
want to change this to `codehilite`, or change `codehilite` to use the `highlight` class as well.
- **FIX**: Use `markdown.extensions.md_in_html` instead of `pymdownx.extrarawhtml` in the default settings as the latter
is no longer available in the latest dependency.
- **NEW**: `pymdownx.superfences` no longer sources any settings from `markdown.extensions.codehilite` and instead uses
`pymdownx.highlight`. No need to specify `markdown.extensions.codehilite` in the default settings.
- **NEW**: Default `pygments_css` class is now set to `highlight` which is `pymdownx.highlight`'s default. If you are
using `pymdownx.superfences`, you use use `highlight`, if you are using `markdown.extensions.codehilite`, then you may
want to change this to `codehilite`, or change `codehilite` to use the `highlight` class as well.
- **FIX**: Use `markdown.extensions.md_in_html` instead of `pymdownx.extrarawhtml` in the default settings as the latter
is no longer available in the latest dependency.

## 2.2.5

- **FIX**: Fix for detecting browser in macOS Catalina.
- **FIX**: Fix for detecting browser in macOS Catalina.

## 2.2.4

- **FIX**: Fix GitHub emoji asset links.
- **FIX**: Fix GitHub emoji asset links.

## 2.2.3

- **FIX**: Linux browser preview issue.
- **FIX**: Linux browser preview issue.

## 2.2.2

- **FIX**: Reload issues in some browsers.
- **FIX**: Reload issues in some browsers.

## 2.2.1

- Add support for Markdown 3+ and Pymdownx 6+.
- Add `viewport` scaling in HTML.
- Add support for Markdown 3+ and Pymdownx 6+.
- Add `viewport` scaling in HTML.

## 2.2.0

- Add basic GitLab support.
- Add per parser support for JavaScript and CSS configurations. Please see documentation to learn the new format.
- Add basic GitLab support.
- Add per parser support for JavaScript and CSS configurations. Please see documentation to learn the new format.

## 2.1.2

- Don't allow live reload on save if using GitHub parser with no OAuth.
- Don't allow live reload on save if using GitHub parser with no OAuth.

## 2.1.1

- Revert `autoNumber` set to `all` in MathJax config.
- Revert alignment left of MathJax display equations as the default has always been center prior to 2.0 releases.
- Revert `autoNumber` set to `all` in MathJax config.
- Revert alignment left of MathJax display equations as the default has always been center prior to 2.0 releases.

## 2.1.0

- Add support for KaTeX math.
- Ensure MathJax properly looks for `\begin{env}...\end{env}`.
- Unified menu.
- Add support for KaTeX math.
- Ensure MathJax properly looks for `\begin{env}...\end{env}`.
- Unified menu.

## 2.0.3

- MathJax should only scan for `arithmatex` classes in HTML.
- MathJax should only scan for `arithmatex` classes in HTML.

## 2.0.2

- Code highlighting should have guessing disabled by default.
- Fix failure when code highlighting has guessing enabled, but the user specified a language name which has no lexer.
- Code highlighting should have guessing disabled by default.
- Fix failure when code highlighting has guessing enabled, but the user specified a language name which has no lexer.

## 2.0.1

- Fix missing code highlight extension.
- Fix build command failing.
- Fix missing code highlight extension.
- Fix build command failing.

## 2.0.0

Please read documentation as there have been big changes in this version which may require updates to your personal
settings.

* Do not vendor Python Markdown. Python Markdown will be acquired via the current markdown dependency.
* Do not vendor Python Markdown. Python Markdown will be acquired via the current markdown dependency.

* Python Markdown configuration changes:
* Python Markdown configuration changes:

* No more defining settings as `extension(option1=a,option2=b)`. Options will be defined as a dictionary.
* You will have to define the full extension name: `markdown.extensions.codehilite`. This will allow you to import
any extension you want outside of Markdown Preview.
* New line to `<br>` conversion has been dropped from GitHub emulation as GitHub no longer does this. Ref issue
#374.
* No more defining settings as `extension(option1=a,option2=b)`. Options will be defined as a dictionary.
* You will have to define the full extension name: `markdown.extensions.codehilite`. This will allow you to import
any extension you want outside of Markdown Preview.
* New line to `<br>` conversion has been dropped from GitHub emulation as GitHub no longer does this. Ref issue
#374.

* Originally a couple pymdownx-extension extensions were ported over to this plugin to give a GitHub-ish feel to
Markdown, these are no longer be included directly, but are included as a dependency. This will provide the latest
versions, and also provide new extensions previously not included. Ref issue #378.
* Originally a couple pymdownx-extension extensions were ported over to this plugin to give a GitHub-ish feel to
Markdown, these are no longer be included directly, but are included as a dependency. This will provide the latest
versions, and also provide new extensions previously not included. Ref issue #378.

* Drop ST2 so we no longer have to provide specially crafted Python Markdown versions when we try to upgrade.
* Drop ST2 so we no longer have to provide specially crafted Python Markdown versions when we try to upgrade.

* Improve yaml front matter parsing: see issue #392.
* Improve yaml front matter parsing: see issue #392.

* Better UML JavaScript injection.
* Better UML JavaScript injection.

* Link contributors in readme.
* Link contributors in readme.

* Remove "magic" Pygments configuration. User will now explicitly configure Pygments CSS injection separately.
* Remove "magic" Pygments configuration. User will now explicitly configure Pygments CSS injection separately.

* Require explicit parser name moving forward instead of default, but provide a deprecation path for the short term.
* Require explicit parser name moving forward instead of default, but provide a deprecation path for the short term.

* Fix GitHub header ID generation. GitHub only lowercases ASCII chars.
* Fix GitHub header ID generation. GitHub only lowercases ASCII chars.

* Ensure default parser is Python Markdown, and enable auto-reload by default.
* Ensure default parser is Python Markdown, and enable auto-reload by default.

* Hopefully better documentation.
* Hopefully better documentation.

* Make flake8 compatible.
* Make flake8 compatible.

* Fix outdated links.
* Fix outdated links.

* Remove MathJax and UML option in favor of a more generalized solution via the pre-existing `css` option.
* Remove MathJax and UML option in favor of a more generalized solution via the pre-existing `css` option.

* Remove `embed_css_for_sublime_output` option in favor of more generalized `include_head` option.
* Remove `embed_css_for_sublime_output` option in favor of more generalized `include_head` option.

## 1.4.3

* Fix issue where Chrome prevents live reload.
* Fix issue where Chrome prevents live reload.

## 1.4.0

* `css` setting can now be an array and contain multiple CSS files (see settings file for more info).
* Updated GitHub style to latest.
* `css` setting can now be an array and contain multiple CSS files (see settings file for more info).
* Updated GitHub style to latest.

## 1.3.0

* Now supports any markdown parser through a generalized method. Now you can map a binary to parser name via
`markdown_binary_map`. Then use the parser name in `enabled_parsers` to use it.
* MultiMarkdown specific settings have been removed. MultiMarkdown should now be configured via `markdown_binary_map`
and `enabled_parsers`.
* Upgraded to Python Markdown 2.6.4.
* Removed internal PyYaml and Pygments. Markdown Preview now uses Package Control dependencies to obtain PyYaml and
Pygments.
* Update kbd CSS for GitHub.
* Now supports any markdown parser through a generalized method. Now you can map a binary to parser name via
`markdown_binary_map`. Then use the parser name in `enabled_parsers` to use it.
* MultiMarkdown specific settings have been removed. MultiMarkdown should now be configured via `markdown_binary_map`
and `enabled_parsers`.
* Upgraded to Python Markdown 2.6.4.
* Removed internal PyYaml and Pygments. Markdown Preview now uses Package Control dependencies to obtain PyYaml and
Pygments.
* Update kbd CSS for GitHub.

## 1.0.3

* The `messages.json` should OK for this time.
* The `messages.json` should OK for this time.

## 1.0.2

* Fixes messages.json and changelog versions.
* Fixes messages.json and changelog versions.

## 1.0.1

* Removed markdown2 parser for its not well maintained and buggy.
* Make Python Markdown parser as default.
* Split the preview commands for *Python Markdown* parser and *GitHub Flavored Markdown* parser.
* Add markdown file build support, build parser are config via the origin `"parser"` settings.
* Add this changelog file for both developers and users.
* Add messages.json which make display of `README.md` and `CHANGES.md`
* Try use `Markdown Extended.tmLanguage` for cheat sheet if you installed `Markdown Extended`.
* Removed markdown2 parser for its not well maintained and buggy.
* Make Python Markdown parser as default.
* Split the preview commands for *Python Markdown* parser and *GitHub Flavored Markdown* parser.
* Add markdown file build support, build parser are config via the origin `"parser"` settings.
* Add this changelog file for both developers and users.
* Add messages.json which make display of `README.md` and `CHANGES.md`
* Try use `Markdown Extended.tmLanguage` for cheat sheet if you installed `Markdown Extended`.

## 1.0.0

* Support for ST3.
* Added Python Markdown parser.
* CSS search first in markdown file directory and the the build-in.
* Support for ST3.
* Added Python Markdown parser.
* CSS search first in markdown file directory and the the build-in.
24 changes: 12 additions & 12 deletions docs/src/markdown/about/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,23 +19,23 @@ any tier you feel comfortable with. No amount is too little. We also accept one

## Bug Reports

1. Please **read the documentation** and **search the issue tracker** to try and find the answer to your question
**before** posting an issue.
1. Please **read the documentation** and **search the issue tracker** to try and find the answer to your question
**before** posting an issue.

2. When creating an issue on the repository, please provide as much info as possible:
2. When creating an issue on the repository, please provide as much info as possible:

- Version being used.
- Operating system.
- Version of Python.
- Errors in console.
- Detailed description of the problem.
- Examples for reproducing the error. You can post pictures, but if specific text or code is required to reproduce
the issue, please provide the text in a plain text format for easy copy/paste.
- Version being used.
- Operating system.
- Version of Python.
- Errors in console.
- Detailed description of the problem.
- Examples for reproducing the error. You can post pictures, but if specific text or code is required to
reproduce the issue, please provide the text in a plain text format for easy copy/paste.

The more info provided, the greater the chance someone will take the time to answer, implement, or fix the issue.

3. Be prepared to answer questions and provide additional information if required. Issues in which the creator refuses
to respond to follow up questions will be marked as stale and closed.
3. Be prepared to answer questions and provide additional information if required. Issues in which the creator refuses
to respond to follow up questions will be marked as stale and closed.

## Reviewing Code

Expand Down
24 changes: 14 additions & 10 deletions docs/src/markdown/extras.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@

## MathJax Support

!!! danger
GitHub and GitLab is not supported with MathJax. You will have to come up with a MathJax config that works for it
and escape problematic syntax that GitHub may try to convert.
/// danger
GitHub and GitLab is not supported with MathJax. You will have to come up with a MathJax config that works for it
and escape problematic syntax that GitHub may try to convert.
///

To render Tex style math in Markdown, you can use the default MathJax configuration that is included with Markdown
Preview or create and reference your own.
Expand Down Expand Up @@ -50,12 +51,14 @@ accommodate certain changes. Check out Arithmatex documentation for more info.

## KaTeX Support

!!! warning
GitLab is already configured for KaTeX by default. You should just include `default` in your CSS and JS list.
/// warning
GitLab is already configured for KaTeX by default. You should just include `default` in your CSS and JS list.
///

!!! danger
GitHub is not supported with KaTeX. You will have to come up with a MathJax config that works for it and escape
problematic syntax that GitHub may try to convert.
/// danger
GitHub is not supported with KaTeX. You will have to come up with a MathJax config that works for it and escape
problematic syntax that GitHub may try to convert.
///

To render Tex style math in Markdown, you can use the default KaTeX configuration that is included with Markdown Preview
or create and reference your own.
Expand Down Expand Up @@ -114,8 +117,9 @@ certain changes. Check out Arithmatex documentation for more info.

## UML Support

!!! danger
GitHub is not supported with UML.
/// danger
GitHub is not supported with UML.
///

If you are using the extension [SuperFences extension][superfences], it has an option to create special, custom fences.
By default, it specifies `flow` and `sequence` languages to generate special code blocks that JavaScript can be applied
Expand Down
43 changes: 22 additions & 21 deletions docs/src/markdown/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,33 +5,34 @@ Preview and build your markdown files quickly in your web browser.
You can use the builtin [Python Markdown][pymd] parser (offline) or use the [GitHub Markdown API][gfm-api] (online) or
[GitLab Markdown API][glfm-api] (online) for the conversion.

!!! note
If you choose the GitHub or GitLab API for conversion (set `parser` to `github` or `gitlab` in your settings), your
code will be sent through HTTPS to GitHub or GitLab for live conversion. In case of GitHub, You'll have [GitHub
Flavored Markdown][gfm-help], syntax highlighting and EMOJI support for free :heart: :gift:. If you make more than
60 calls a day, be sure to set your GitHub API key in the settings :smile:.
/// note
If you choose the GitHub or GitLab API for conversion (set `parser` to `github` or `gitlab` in your settings), your
code will be sent through HTTPS to GitHub or GitLab for live conversion. In case of GitHub, You'll have [GitHub
Flavored Markdown][gfm-help], syntax highlighting and EMOJI support for free :heart: :gift:. If you make more than
60 calls a day, be sure to set your GitHub API key in the settings :smile:.
///

## Features

- Markdown preview using the [python-markdown][pymd] with syntax highlighting via Pygments and optional 3rd party
extensions ([pymdown-extensions][pymdownx-docs] included by default).
- Markdown previews via the GitHub API.
- Markdown previews via the GitLab API.
- Ability use other external Markdown parsers.
- Build markdown file using Sublime Text build system.
- Browser preview auto reload on save if you have the [LiveReload plugin][live-reload] installed.
- Configurable CSS and JavaScript assets with overriding if needed.
- YAML support thanks to @tommi.
- Clipboard selection and copy to clipboard thanks to @hexatrope.
- MathJax support : $\frac{\pi}{2}$ thanks to @bps10.
- HTML template customization thanks to @hozaka.
- Embed images as base64.
- Strip out MultiMarkdown CriticMarkup.
- Markdown preview using the [python-markdown][pymd] with syntax highlighting via Pygments and optional 3rd party
extensions ([pymdown-extensions][pymdownx-docs] included by default).
- Markdown previews via the GitHub API.
- Markdown previews via the GitLab API.
- Ability use other external Markdown parsers.
- Build markdown file using Sublime Text build system.
- Browser preview auto reload on save if you have the [LiveReload plugin][live-reload] installed.
- Configurable CSS and JavaScript assets with overriding if needed.
- YAML support thanks to @tommi.
- Clipboard selection and copy to clipboard thanks to @hexatrope.
- MathJax support : $\frac{\pi}{2}$ thanks to @bps10.
- HTML template customization thanks to @hozaka.
- Embed images as base64.
- Strip out MultiMarkdown CriticMarkup.

## Support

- Any bugs about Markdown Preview please feel free to report [here][issue].
- And you are welcome to fork and submit pull requests.
- Any bugs about Markdown Preview please feel free to report [here][issue].
- And you are welcome to fork and submit pull requests.

## Attribution

Expand Down
Loading

0 comments on commit a1b327a

Please sign in to comment.