-
Notifications
You must be signed in to change notification settings - Fork 28
1.0.0 config redesign, docs rewrite, and demo tooling #75
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.
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
Changes from all commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
fed1fe5
Breaking: rename config, add render-attribute and linebreak features
jmnote 1de4bd5
Add docs, config reference, and demo/dev tooling
jmnote 92bb6f8
Fix chem/ignoreHtmlClass bugs, rework demo tooling, rewrite config docs
jmnote 581b43d
docs: trim trailing blank line in configuration.md
jmnote e44739b
Flatten $wgSmjCdn/$wgSmjExtraDelimiters, fix docs, trim trailing blan…
jmnote bf8d298
hack/mathjax.sh: fix CDN version sed for the flattened extension.json…
jmnote 180302c
composer.json: add license field to silence composer validate's warning
jmnote e10c006
Split `make mathjax` into local-only `make local-mathjax`
jmnote db178f1
Rename $wgSmjExtraDelimiters* -> $wgSmjDelimiters*
jmnote 110282c
docs/configuration.md: fix stale #wgsmjextradelimitersenabled anchor
jmnote File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| # AGENTS.md | ||
|
|
||
| Run `make checks` before committing. `test` runs plain PHP scripts | ||
| (`php tests/*.php`), not PHPUnit. `phpcs` needs `composer install`, which | ||
| `make` does automatically. | ||
|
|
||
| `hack/demo/demo.sh` / `make screenshots [demo]` render a demo through a | ||
| local Docker MediaWiki and regenerate `docs/screenshots/*.png`. Only run | ||
| this when asked to, or when a change affects rendering (`resources/`, | ||
| `hack/demo/demos.yaml`) — not for routine changes. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,18 +1,31 @@ | ||
| .PHONY: checks test phpcs mathjax | ||
| .PHONY: checks test phpcs local-mathjax screenshots | ||
|
|
||
| MATHJAX_VERSION_LOCAL ?= 4.1.3 | ||
| MATHJAX_VERSION_CDN ?= 4 | ||
| LOCAL_MATHJAX_VERSION ?= 4.1.3 | ||
|
|
||
| checks: test phpcs ## Everything CI runs before merging (needs `composer install`, PHP >= 8.2) | ||
|
|
||
| test: ## Run the pure-PHP test suites | ||
| php tests/QuotesTest.php | ||
| php tests/RevisionOverridesTest.php | ||
|
|
||
| phpcs: vendor/autoload.php ## parallel-lint + minus-x + phpcs against the MediaWiki coding standard | ||
| composer test | ||
|
|
||
| local-mathjax: ## Pin the bundled local MathJax submodule, e.g. `make local-mathjax LOCAL_MATHJAX_VERSION=4.1.3` | ||
| hack/local-mathjax.sh $(LOCAL_MATHJAX_VERSION) | ||
|
|
||
| vendor/autoload.php: composer.json | ||
| composer install --no-progress | ||
|
|
||
| mathjax: ## Pin the local MathJax submodule + CDN major version, e.g. `make mathjax MATHJAX_VERSION_LOCAL=4.1.3 MATHJAX_VERSION_CDN=4` | ||
| hack/mathjax.sh $(MATHJAX_VERSION_LOCAL) $(MATHJAX_VERSION_CDN) | ||
| screenshots: ## Screenshot a demo page, e.g. `make screenshots custom01` (no demo = every demo in hack/demo/demos.yaml) | ||
| hack/demo/demo.sh screenshot $(filter-out $@,$(MAKECMDGOALS)) | ||
|
|
||
| # Swallows the extra word in `make screenshots custom01` so make doesn't | ||
| # treat "custom01" as a target of its own and fail with "No rule to make | ||
| # target". Scoped to only fire when `screenshots` is actually one of the | ||
| # invoked goals, so an unrelated typo like `make cheks` still fails loudly | ||
| # instead of silently no-op'ing. | ||
| ifneq ($(filter screenshots,$(MAKECMDGOALS)),) | ||
| %: | ||
| @: | ||
| endif |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,185 @@ | ||
| # Configuration | ||
|
|
||
| Full reference for every `$wgSmj*` setting, plus the `SimpleMathJaxAttributes` | ||
| hook for extending it in code. The quick-reference table in the | ||
| [README](../README.md#optional-settings) links here for full explanations | ||
| and examples. Upgrading from before 1.0.0? See the | ||
| [migration guide](mig-1.0.md) instead. | ||
|
|
||
| ## Settings reference | ||
|
|
||
| | Setting name | Default value | Description | | ||
| | ------------------------ | ------------- | ----------- | | ||
| | `$wgSmjCdnEnabled` | `true` | Whether to load MathJax from a CDN instead of the bundled local copy | | ||
| | `$wgSmjCdnVersion` | `'4'` | MathJax version to load from the CDN | | ||
| | `$wgSmjScale` | `1` | `MathJax.chtml.scale` | | ||
| | `$wgSmjEnableMenu` | `true` | `MathJax.options.enableMenu` | | ||
| | `$wgSmjDelimitersEnabled` | `false` | Whether to also scan for bare delimiters (e.g. `$...$`) outside `<math>`/`<chem>` | | ||
| | `$wgSmjDelimitersInlineMath` | `[]` | Inline math delimiter pairs, e.g. `[['$','$']]` | | ||
| | `$wgSmjDelimitersDisplayMath` | `[]` | Display math delimiter pairs, e.g. `[['$$','$$']]` | | ||
| | `$wgSmjAllowedAttributes` | `[]` | List of generic HTML attributes to carry over to the output `<span>` | | ||
| | `$wgSmjIgnoreHtmlClass` | `'mathjax_ignore\|comment\|`<br>`diff-(context\|`<br>`addedline\|deletedline)'` | `MathJax.options.ignoreHtmlClass` | | ||
| | `$wgSmjRevisionOverrides` | `[]` | Switch the configuration according to the article's revision | | ||
|
|
||
| ### `$wgSmjCdnEnabled` | ||
|
|
||
| The default follows the latest 4.x release. To pin the CDN to an exact | ||
| version, set it explicitly: | ||
|
|
||
| ```php | ||
| wfLoadExtension( 'SimpleMathJax' ); | ||
| $wgSmjCdnVersion = '4.1.3'; | ||
| ``` | ||
|
|
||
| To use the local MathJax module, disable the CDN. | ||
|
|
||
| ```php | ||
| wfLoadExtension( 'SimpleMathJax' ); | ||
| $wgSmjCdnEnabled = false; | ||
| ``` | ||
|
|
||
| When working from the Git repository, initialize or update the bundled | ||
| MathJax submodule with `make local-mathjax` — see | ||
| [Updating MathJax](development.md#updating-mathjax) for version | ||
| selection. Normal extension packages already include the bundled MathJax | ||
| resources and do not require Git commands. | ||
|
|
||
| ### `$wgSmjScale` | ||
|
|
||
| `$wgSmjScale` is passed straight through as MathJax's own `chtml.scale` | ||
| option — a multiplier on the default font size, where `1` is 100% (the | ||
| default) and, say, `1.5` is 150%. Any positive number works; there's no | ||
| built-in minimum or maximum. | ||
|
|
||
| ```php | ||
| wfLoadExtension( 'SimpleMathJax' ); | ||
| $wgSmjScale = 1.5; | ||
| ``` | ||
|
|
||
| ### `$wgSmjEnableMenu` | ||
|
|
||
| If you want to disable MathJax context menu, set `$wgSmjEnableMenu`. | ||
|
|
||
| ```php | ||
| wfLoadExtension( 'SimpleMathJax' ); | ||
| $wgSmjEnableMenu = false; | ||
| ``` | ||
|
|
||
| ### `$wgSmjDelimitersEnabled` | ||
|
|
||
| By default, `$wgSmjDelimitersEnabled` is `false`, so only TeX wrapped in | ||
| `<math>` or `<chem>` is recognized — bare `$...$`/`$$...$$` delimiters are | ||
| left as plain text, and `$wgSmjDelimitersInlineMath`/`DisplayMath` go | ||
| unused (as does [`$wgSmjIgnoreHtmlClass`](#wgsmjignorehtmlclass)'s | ||
| diff/comment protection, since there's nothing for it to protect against). | ||
| Set `Enabled` to `true` and list the delimiter pairs yourself to also | ||
| recognize bare delimiters: | ||
|
|
||
| ```php | ||
| wfLoadExtension( 'SimpleMathJax' ); | ||
| $wgSmjDelimitersEnabled = true; | ||
| $wgSmjDelimitersInlineMath = [ [ '$', '$' ] ]; | ||
| $wgSmjDelimitersDisplayMath = [ [ '$$', '$$' ] ]; | ||
| ``` | ||
|
|
||
| ### `$wgSmjAllowedAttributes` | ||
|
|
||
| `$wgSmjAllowedAttributes` is the administrator-defined allow-list of generic | ||
| HTML attributes to copy from `<math>`/`<chem>` to the output `<span>`. No | ||
| attributes are copied by default; add the attribute names you want. Values | ||
| are still passed through MediaWiki's attribute sanitizer. A common case is | ||
| wanting a CSS styling hook plus a hover tooltip, without carrying over `id` | ||
| (which must be unique on the page, so an editor-supplied one can collide with | ||
| an anchor link (`#section`) or another element/JS gadget): | ||
|
|
||
| ```php | ||
| wfLoadExtension( 'SimpleMathJax' ); | ||
| $wgSmjAllowedAttributes = [ 'class', 'title' ]; | ||
| ``` | ||
|
|
||
| `display` and `chem` are unrelated to this list and always work regardless — | ||
| see [Display styles](displaystyle.md). | ||
|
|
||
| ### `$wgSmjIgnoreHtmlClass` | ||
|
|
||
| You probably don't need to change this — the default already covers what it | ||
| needs to: | ||
|
|
||
| ``` | ||
| mathjax_ignore|comment|diff-(context|addedline|deletedline) | ||
| ``` | ||
|
|
||
| `mathjax_ignore` lets an editor skip one `<math>`/`<chem>` by adding that | ||
| class, if `class` is allowed via | ||
| [`$wgSmjAllowedAttributes`](#wgsmjallowedattributes) (empty by default). | ||
| `comment` and `diff-(context|addedline|deletedline)` match what MediaWiki | ||
| puts on edit-summary and diff-table elements, protecting them — though only | ||
| if [`$wgSmjDelimitersEnabled`](#wgsmjdelimitersenabled) is on (see | ||
| [Rendering internals](development.md#rendering-internals) for why). | ||
|
|
||
| **Don't** replace the whole pattern with just your own class when extra | ||
| delimiters are on — the default's diff/comment protection goes with it: | ||
|
|
||
| ```php | ||
| wfLoadExtension( 'SimpleMathJax' ); | ||
| $wgSmjDelimitersEnabled = true; | ||
| // Don't: replaces the whole pattern, so it loses diff/comment protection. | ||
| $wgSmjIgnoreHtmlClass = 'my_custom_class'; | ||
| ``` | ||
|
|
||
| **Do**, only if you really need your own class, extend the default with `|` | ||
| instead — and add `class` to `$wgSmjAllowedAttributes` so it survives on | ||
| individual `<math class="my_custom_class">` elements: | ||
|
|
||
| ```php | ||
| wfLoadExtension( 'SimpleMathJax' ); | ||
| $wgSmjDelimitersEnabled = true; | ||
| // Do, if you really need it: extends the default pattern instead of replacing it. | ||
| $wgSmjIgnoreHtmlClass = 'mathjax_ignore|comment|diff-(context|addedline|deletedline)|my_custom_class'; | ||
| $wgSmjAllowedAttributes = [ 'class' ]; | ||
| ``` | ||
|
|
||
| ### `$wgSmjRevisionOverrides` | ||
|
|
||
| `$wgSmjRevisionOverrides` applies different settings to different ranges of | ||
| an article's revisions. This doesn't happen on its own — a past revision only | ||
| keeps rendering with the settings that were in effect when it was current if | ||
| you map that revision range to those settings yourself, as below. Each entry | ||
| is an array whose other keys are the overrides to apply, plus: | ||
|
|
||
| - A `min` and/or a `max` (the revision id bounds it applies to; either end | ||
| is open if omitted). Both bounds are inclusive. Revision ids increase | ||
| across the whole wiki, not per page — check the page's history for the | ||
| actual numbers rather than guessing from its edit count. | ||
| - Only the keys written inside `[]` are overwritten — the rest of your | ||
| `$wgSmj*` settings stay as they are. | ||
| - When more than one entry matches the same revision, later entries in the | ||
| list win — each one overwrites whatever the ones before it set for the | ||
| same key. | ||
| - Preview, History and Special pages are treated as revision `0`, a base | ||
| case where no entry ever applies, so they always render with the plain | ||
| `$wgSmj*` settings instead. | ||
|
|
||
| ```php | ||
| wfLoadExtension( 'SimpleMathJax' ); | ||
| $wgSmjDelimitersEnabled = false; // To match the preview with the actual rendering, write the latest settings in the base case | ||
| $wgSmjRevisionOverrides = [ | ||
| [ 'max' => 50000, 'wgSmjDelimitersEnabled' => true ], | ||
| [ 'min' => 50001, 'max' => 60000, 'wgSmjDelimitersEnabled' => false ], | ||
| ]; | ||
| ``` | ||
|
|
||
| ## Hooks | ||
|
|
||
| The hook `SimpleMathJaxAttributes` is available to add attributes to the span around the math. (Note that this process is performed only for `<math>` and `<chem>` elements, and other delimiters are handled directly by MathJax.) This hook provides you with the opportunity to ensure that your own code does not interfere with MathJax's rendering of math. | ||
|
|
||
| For instance, if Lingo's JS functions are called before MathJax is invoked, then it is possible that Lingo will change the text so that MathJax could no longer render the math. | ||
|
|
||
| Lingo understands that [it should not touch anything inside an element with the class `noglossary`](https://www.mediawiki.org/wiki/Extension:Lingo#Excluding_text_from_markup) so the following code can be used to keep Lingo from ruining math: | ||
|
|
||
| ```php | ||
| $wgHooks['SimpleMathJaxAttributes'][] | ||
| = function ( array &$attributes, string $tex, array $args = [] ) { | ||
| $attributes['class'] .= ' noglossary'; | ||
| }; | ||
| ``` | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The repository stores
resources/MathJaxonly as a gitlink, while the release workflow merely invokesgh release createand uploads no archive containing initialized submodule contents. Consequently, users of the generated GitHub source packages who follow this paragraph and set$wgSmjCdnEnabled = falsewill not haveresources/MathJax/tex-chtml.jsand local rendering will fail; either package the submodule contents or instruct package users to obtain them.Useful? React with 👍 / 👎.