This is an internal change that only affects developers of our theme. This PR:
- **upgrades `Stylelint` to `v15`!**
- among other things, this leads to the deprecation of many stylistic rules, which overlap with Prettier
- it also sees the addition of new rules that catch more errors, especially `declaration-property-value-no-unknown`!
- upgrades the accompanying standard config (the SCSS one extends the first-party one); this new config disables the deprecated rules that overlap with Prettier
- removes a now-unneeded plugin that disables overlapping rules
- moves the `stylelint` config object to `package.json` - now we have one less file (particularly important since people still clone this repo)
There were very few new changes; I combined one string that had a dangling `+` in an SCSS warning, and have temporarily disabled the `at-rule-empty-line-before` rule (which also picks up on SCSS `@includes`).
After some discussion in #1166, I realized that our prettier workflow is somewhat broken! This PR fixes it, by:
- separating Stylelint & Prettier (and removing `stylelint-prettier`) to clearly separate linting versus formatting
- this is also helpful for the upcoming upgrading of Stylelint
- having Prettier ignore `assets/js/zzzz-search-data.json`; on `main`, `npm run format` fails because of this file (Prettier doesn't know how to interpret the front matter)
- change `npm test` to run both Stylelint and Prettier on CI (uses `npm-run-all` utility
- had to add one `// prettier-ignore` in `_includes/mermaid_config.js`, which I think is reasonably placed
- removing an unused `script` (that doesn't work!)
This is a no-op on the site itself, just for our dev environment/CI.
Ref: https://github.com/just-the-docs/just-the-docs/pull/1166#discussion_r1110397592.
---
Separately, upgrading to Stylelint 15 will come with another interaction - the [deprecation of stylistic rules](https://stylelint.io/migration-guide/to-15#deprecated-stylistic-rules) + shift to Prettier should be nice!
These changes accommodate for some difference in the HTML structure AsciiDoc produces for source code listings:
* proper padding for source code listings
* proper vertical margin after source code listings
* proper placement of the copy button if enabled
Closes#1163
In my other cleaning, I also noticed:
- the contributors pane on the homepage is broken
- the following link to a repo page in the search docs is broken
<img width="762" alt="Screenshot 2023-01-03 at 6 41 49 PM" src="https://user-images.githubusercontent.com/14893287/210474679-bcb9af23-0a4e-4999-a0ec-f06d967ea726.png">
In particular, the generated HTML is
```html
<a href="/blob/main/assets/js/zzzz-search-data.json">this content</a>
```
Looking at the source code for both features
```html
<ul class="list-style-none">
{% for contributor in site.github.contributors %}
<li class="d-inline-block mr-1">
<a href="{{ contributor.html_url }}"><img src="{{ contributor.avatar_url }}" width="32" height="32" alt="{{ contributor.login }}"></a>
</li>
{% endfor %}
</ul>
```
```md
[this content]({{ site.github.repository_url }}/blob/main/assets/js/zzzz-search-data.json).
```
It's clear that `site.github` is not being populated. This is controlled by the GitHub Metadata/[`jekyll-github-metadata`](http://jekyll.github.io/github-metadata/) plugin.
I'm not when this stopped working. If I had to guess, I think this is packaged as part of the `github-pages` gem; so, when the site moved off of it a while back, we never noticed this regression. This is the type of thing that can hopefully be caught by regression tests in the future.
This PR re-adds the plugin. I've opted to only add it to the `Gemfile` but not the `gemspec` so that it only affects our site. In other words, JtD does not have `jekyll-github-metadata` as a runtime dependency (since none of our theme code relies on it). Happy to change that if we'd like.
---
In the future,
- short-term: I can write a filter that removes dependabot from our contributors
- longer-term: we could rewrite the "last edited on GitHub" feature to instead use `jekyll-github-metadata`. this would necessitate us to make it a runtime dependency, and it also wouldn't work as well for users of GitLab or other alternatives.
This PR:
- matricizes (?) the OS parameter: we now also test on `windows` and `macOS`
- matricizes the Ruby version parameter: we now also test on Ruby 2.7
- loosens the `.gemspec` requirement for `bundler` to allow things greater than `2.3.5`
- interestingly, this is because the Ruby 2.7 container has a **later** version of bundler than the 3.1 one!
The last point makes this user-facing, and thus I'll trigger a release for this PR sometime soon.
These only apply to the `jekyll-build` job. Here, I think we have a broader obligation to support various use-cases (maybe they're deploying on GitLab, generating files locally, etc.); in contrast, the `github-pages` gem is used exclusively for deploying to GitHub Pages, so we should try to match that environment exactly.
This PR closes#1145.
This is a small PR that:
- adds a `fixtures/Gemfile-github-pages`, the minimum gemfile necessary to build the site
- adds a new Actions workflow to build the site with that gemfile
In the future, this should prevent issues like #1074, where we push a change that passes the `jekyll` CI but fails to build on `github-pages` (and its dependencies - which in this case, was an older version of ruby sass).
(to be honest - not super happy with the code duplication, but I also think we'll have different build matrices for the different versions, so I'm fine with this for now)
Part of (but does not close) #1145.
Hi there!
Thank you for the great theme! I am a happy user and was delighted to see that mermaid support has landed.
In some cases the usage of jsDelivr might not be possible for technical or compliance reasons.
This commit adds a second way to include the mermaid lib by specifying a path in the mermaid config. This way a local version of the lib can be used.
It should be fully backwards compatible, not requiring any action by users that already include the lib from the CDN.
I already added some documentation, but I am also happy to extend this, if this change is generally well-received.
Cheers,
Christian
When customizing `$code-background-color` in `dark.scss`, the result is a multi-color background. (see https://github.com/just-the-docs/just-the-docs/issues/1121#issuecomment-1374976843)
This makes OneDarkJekyll code block colors the same as the specified `$code-background-color`, and uses the `$default-body-color` as the line number text color, which can otherwise be invisible due to the default being black and is hard to see on a very dark code block background.
In #1058, I noted:
> Tangentially related work:
> ...
> - better annotate new features (motivated by writing these docs)
> - we should add "New" to new features :)
> - we should note when a feature was introduced (I think this is a core part of most software documentation)
> - we should annotate things that are "Advanced" in so far as the average Just the Docs user will not use them / they require significant Jekyll knowledge
>
This came up again in https://github.com/just-the-docs/just-the-docs/discussions/1136#discussioncomment-4716253, so I think it's best for us to resolve this sooner rather than later.
This PR is me doing that. I:
- have added a headings-level "New" label to every new heading introduced since `v0.3`
- added, when possible, inline YAML comments when new configuration options have been introduced
I did this by scanning through the CHANGELOG and selecting each feature that is either tagged with `Add` and has documentation.
I may have also missed any new features, so some double-checking would be helpful!
The migration guide is intended to help those using Just the Docs (as a theme or a remote theme) switch from v0.3.3 to v0.4.0.
Co-authored-by: Matt Wang <matt@matthewwang.me>
This is an alternative PR that resolves#1011. Unlike #1013, this PR defines a *new* SASS file, `_sass/custom/setup.scss`, specifically designed for new custom variables (and other SASS-only constructs). It's imported after our `support` SASS files are (functions, variables), but otherwise is imported before all other files (ex, when CSS is emitted).
So, custom callout colors can now be defined in this file. I also move the custom callout colors present in `custom.scss` to the right location.
I've added some docs that briefly explain how to use the feature. Feedback is welcome!
---
As an aside, I chose not to add a `_includes/css` file that imports this, and then import that file. I think that's only necessary if we're trying to render liquid somehow in the SASS file; since we're not trying to do that for `setup.scss`, I've opted to not include it. If we think this is relevant, I can re-add it.
Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
This is a prototype for review and discussion. My use and testing of this PR is on top of 6d9d41359c46882d9b64a446d5a83fac5b3e20a7. The changes are trival to rebase to `main` and I'm happy to do so if this prototype moves forward.
* Feature request details in linked issue, fixesjust-the-docs/just-the-docs#1067
* I welcome feedback and all discussion
* A draft doc site of mine using this PR is at https://docs.hidale.com/
To use the prototype, the two include files need to be customized. Here are mine from the draft website 9c0d836408
Co-authored-by: Matt Wang <matt@matthewwang.me>
In touching up the migration guide, I noticed that many of our documentation site links are broken! For example, on the homepage, this link:
<img width="782" alt="screenshot of homepage; code snippet is in next block" src="https://user-images.githubusercontent.com/14893287/210462690-31aa7bf5-dd79-4e8f-a3c5-1213e73771c4.png">
which has the following href
```code
<a href="/just-the-docs/just-the-docs/CHANGELOG/">the CHANGELOG</a>
```
duplicates the `baseurl` twice. There are 14 such broken links across the site. Each link duplicates the `baseurl` and `link` tags, which has since been resolved with links being relative by default (there's a set of PRs that document this - I can't find the exact paper trail right now).
To resolve this, I:
- find and replace site-wide `{{ site.baseurl }}{% link` with `{% link`
- tested each link, which now works properly locally *and* on the deploy preview
I'm surprised we didn't catch this earlier! I also could be missing something else, in which case feedback on this PR is certainly welcome.
This PR corrects the change to `/_sass/search.scss` made in 551398f. This change tried to set the `padding-**top**` property to **two** values rather than set the `padding` property to these values (to represent the vertical and horizontal padding values).
I just reviewed 551398f and believe that this should be the other half of the fix proposed by just-the-docs/just-the-docs#1104.
