A modern, high customizable, responsive Jekyll theme for documentation with built-in search.
Hope your April is going well! This new release of Just the Docs is relatively minor. It has one breaking change: we've reverted the import order of setup.scss
to be before color schemes (introduced in v0.4.2
). In addition, we include two requested fixes: color contrast issues with ::selection
and using Just the Docs with mermaid versions >=10
.
We've marked this as a minor version bump due to the breaking change. In the next section, we briefly outline what migration steps should be. Users who did not migrate to v0.4.2
or who do not have a custom setup.scss
are guaranteed no breaking changes.
As always, we'd love your feedback. Open an issue or start a discussion for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs!
v0.5.0
Migration: users with a custom setup.scss
cannot rely on variables or functions defined in color_scheme
. This reverts to the behaviour in v0.4.1
. Users should instead move those variables or functions to the color_scheme
files themselves.
For more, refer to the migration guide.
v0.5.0
Users who have not pinned the theme version will be automatically upgraded to v0.5.0
the next time they build their site.
To use this release explicitly as a remote theme:
remote_theme: just-the-docs/[email protected]
To use this version explicitly as a gem-based theme, pin the version in your Gemfile
and re-run bundle install
or bundle update just-the-docs
:
gem "just-the-docs", "0.5.0"
To use and pin a previous version of the theme, replace the 0.5.0
with the desired release tag.
setup.scss
(#1184)" by [@mattxwang] in [#1209]::selection
(reverting to browser defaults) [@mattxwang] in [#1208]v10
, bundle all mermaid code in component by [@mattxwang] in [#1190]just-the-docs.png
, search.svg
) by [@mattxwang] in [#1107]CODE_OF_CONDUCT
, docker-compose
, and Dockerfile
files from site by [@mattxwang] in [#1187]Full Changelog: https://github.com/just-the-docs/just-the-docs/compare/v0.4.2...v0.5.0
Hello! We're back again with another small release. Like v0.4.1
, this release is a semver patch: it only includes bugfixes, and is fully backwards-compatible.
The big highlight of this theme is fixing our light scheme code highlighting contrast issues; this was one of our most-requested features! This change is fully backwards-compatible; users can opt-in to our old highlighting theme by using legacy_light
instead of light
.
As always, we'd love your feedback. Open an issue or start a discussion for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs!
v0.4.2
Users who have not pinned the theme version will be automatically upgraded to v0.4.2
the next time they build their site.
To use this release explicitly as a remote theme:
remote_theme: just-the-docs/[email protected]
To use this RC explicitly as a gem-based theme, pin the version in your Gemfile
and re-run bundle install
or bundle update just-the-docs
:
gem "just-the-docs", "0.4.2"
To use and pin a previous version of the theme, replace the 0.4.2
with the desired release tag.
color_schemes
by [@mattxwang] in [#1173]setup.scss
by [@mattxwang] in [#1184]Full Changelog: https://github.com/just-the-docs/just-the-docs/compare/v0.4.1...v0.4.2
Hello! We hope you've been enjoying the new v0.4.0
; we appreciate all the feedback we've gotten already! As promised, future releases will be small with simple steps to upgrade. This is one of them! v0.4.1
is a semver patch: it only includes bugfixes, and is fully backwards-compatible.
As always, we'd love your feedback. Open an issue or start a discussion for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs!
v0.4.1
Users who have not pinned the theme version will be automatically upgraded to v0.4.1
the next time they build their site.
To use this release explicitly as a remote theme:
remote_theme: just-the-docs/[email protected]
To use this RC explicitly as a gem-based theme, pin the version in your Gemfile
and re-run bundle install
or bundle update just-the-docs
:
gem "just-the-docs", "0.4.1"
To use and pin a previous version of the theme, replace the 0.4.1
with the desired release tag.
bundler
by @mattxwang in #1165
[$md, $nav-width + $content-width]
by @Dima-369 in #1177
OneDarkJekyll
files by @mattxwang in #1167
jekyll-github-metadata
to docs site by @mattxwang in #1108
Full Changelog: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1
We're so excited to release Just the Docs v0.4.0
! This release has been almost a year in the making - after our new maintenance team has taken over the project, we've added two years of backlogged features and bugfixes to modernize the theme. This CHANGELOG will summarize some of the key changes, discuss migrations strategies, and outline broad future plans for this theme.
v0.4.0
contains many new features and bugfixes. We enumerate all of them in further sections in this changelog; however, we'd like to call out some of the most-requested changes:
After usage instructions and the roadmap, we enumerate all changes from v0.3.3
.
v0.4.0
Unlike pre-releases, v0.4.0
is a new semver minor release for the theme. That means that users who have not pinned the theme version will be automatically upgraded to v0.4.0
the next time they build their site.
To use this release explicitly as a remote theme:
remote_theme: just-the-docs/[email protected]
To use this RC explicitly as a gem-based theme, pin the version in your Gemfile
and re-run bundle install
or bundle update just-the-docs
:
gem "just-the-docs", "0.4.0"
If you would prefer to not upgrade, you can enforce that explicitly:
Gemfile
, like sogem "just-the-docs", "0.3.3"
remote_theme
, like soremote_theme: just-the-docs/[email protected]
We've developed a new migration guide for users to migrate from version v0.3.3
to v0.4.0
. It outlines major changes in project maintenance (e.g. new repository link, team) as well as breaking changes that may break your site (and potential solutions). We suggest that all users refer to the guide before manually upgrading their site.
For the vast majority of users, we do not anticipate that this will be a breaking change. The major touch points are surrounding new includes, navigation (ordering, pages, and collections), the favicon, and a shift to relative URLs. However, users who heavily customize the theme (primarily by overriding includes) will likely have to make minor changes.
Given the length of features added in this release, users may want to incrementally upgrade through the pre-releases. To follow this approach, read this changelog from v0.4.0.rc1
to v0.4.0.rc5
; this breaks down the release into small chunks, each of which should be easier to upgrade. v0.4.0.rc5
is identical to this release.
For support with migrating to v0.4.0
, open an issue or start a discussion and let us know!
Moving forward, we plan to release more frequently with smaller, bite-sized changes. This should make it easier for users to upgrade in the future!
Broadly, many features are still on the radar. We anticipate the rest of v0.4.x
to be bugfixes surrounding this new release.
For version v0.5
, our roadmap includes:
In future versions, we also plan on:
Have ideas for what's next, or want to get involved? Open an issue or start a discussion and let us know! We're looking for more contributors and maintainers to help us develop the theme.
nav_fold
(no PR)absolute_url
by relative_url
, by [@svrooij] in [#544]_includes
by [@burner1024] in [#364]nav_footer_custom
include by [@nathanjessen] in [#474]mermaid
config to use mermaid_config.js
include, only require mermaid.version
in _config.yml
by [@mattxwang] in [#909]<blockquote>
by [@mattxwang] in [#965]favicon.ico
via site.static_files
by [@pdmosses] in [#1095]lunr
Liquid and JS code by [@diablodale] in [#1068]_sass/custom/setup.scss
for variable definition by [@mattxwang] in [#1135]site.collections_dir
if exists by [@alexsegura] in [#519]overflow-x: auto
to figure.highlight
by [@iridazzle] in [#727]overflow-wrap: word-break
to body
by [@iridazzle] in [#889]vendor/
in Jekyll config by [@manuelhenke] in [#941]text-decoration
values by [@mattxwang] in [#967]custom.scss
; puts at end by [@deseo] in [#1010]title
if jekyll-seo-tag
not in users's plugins by [@Tom-Brouwer] in [#1040]favicon.html
, shifts content to head_custom.html
by [@mattxwang] in [#1027]reversed
, deprecate desc
for nav child_nav_order
by [@jmertic] in [#1061]child.child_nav_order
to node.child_nav_order
by [@mattxwang] in [#1065]/
as SASS division by [@mattxwang] in [#1074]
declaration-block-no-redundant-longhand-properties
by [@simonebortolin] in [#1102]padding
property value pair in labels.scss
by [@SConaway] in [#1104]<svg>
icons by [@captn3m0] in [#1110]padding
property value pair in search.scss
by [@kevinlin1] in [#1123]webrick
to Gemfile
by [@mattxwang] in [#799]master
-> main
by [@pmarsceill] in [#776]jekyll-anchor-headings
, lunr.js
by [@mattxwang] in [#1071]ol
by [@pdmosses] in [#856]custom_head
to add a custom favicon by [@UnclassedPenguin] in [#814]_
-prefix for collections by [@max06] in [#1091]v0.4
by [@mattxwang] in [#1138]ol
on index.md
by [@pmarsceill] in [#778]index.md
by [@sehilyi] in [#499]index.md
by [@nathanjessen] in [#473]README
on _config.yml
by [@ivanskodje] in [#891]lunr
index code by [@diablodale] in [#1139]README
demo video by [@codewithfan] in [#1097]Hi everyone, we're so excited to finally release v0.4.0
! For posterity's sake, we're going to release v0.4.0.rc5
and then immediately re-release it as v0.4.0
; this should make it more clear what changes were introduced in the lead up to the minor release.
This RC does not introduce any major user-facing features. It adds more customizability for custom SCSS variables (fixing a bug with callout introduction order), lunr
indexing, and loading mermaid
locally. In addition, it fixes bugs introduced in .rc4
: incorrect CSS, inconsistencies with code block backgrounds in dark theme, and the copy code button. It also adds a migration guide for users coming from v0.3.3
.
v0.4.0.rc5
Simlar to the prior release, v0.4.0.rc5
is a release candidate for the theme (i.e., a pre-release) with release v0.4.0
following immediately after. While we don't anticipate many users using this RC, it is still possible to opt-in.
To use this RC explicitly as a remote theme:
remote_theme: just-the-docs/[email protected]
To use this RC explicitly as a gem-based theme, pin the version in your Gemfile
and re-run bundle install
or bundle update just-the-docs
:
gem "just-the-docs", "0.4.0.rc5"
By default, users will not be upgraded to 0.4.0.rc5
. To enforce that explicitly, either:
Gemfile
, like sogem "just-the-docs", "0.3.3"
remote_theme
, like soremote_theme: just-the-docs/[email protected]
lunr
Liquid and JS code by [@diablodale] in [#1068]_sass/custom/setup.scss
for variable definition by [@mattxwang] in [#1135]padding
property value pair in search.scss
by [@kevinlin1] in [#1123]README
demo video by [@codewithfan] in [#1097]lunr
index code by [@diablodale] in [#1139]v0.4
by [@mattxwang] in [#1138]Happy new year! We're celebrating with another pre-release, with features that should help theme users better adapt to changes moving forward. We aim to re-release this as v0.4.0
, with only few changes.
Notable new additions include:
The roadmap to v0.4.0
is small. We are only looking to:
v0.3.3
to v0.4.0
Have any questions, thoughts, or concerns? We'd love to hear from you! Please open an issue or start a discussion and let us know!
v0.4.0.rc4
Simlar to the prior release, v0.4.0.rc4
is a release candidate for the theme (i.e., a pre-release) with release v0.4.0
coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to v0.4.0.rc4
.
To use this RC explicitly as a remote theme:
remote_theme: just-the-docs/[email protected]
To use this RC explicitly as a gem-based theme, pin the version in your Gemfile
and re-run bundle install
or bundle update just-the-docs
:
gem "just-the-docs", "0.4.0.rc4"
By default, users will not be upgraded to 0.4.0.rc4
. To enforce that explicitly, either:
Gemfile
, like sogem "just-the-docs", "0.3.3"
remote_theme
, like soremote_theme: just-the-docs/[email protected]
favicon.ico
via site.static_files
by [@pdmosses] in #1095
custom.scss
; puts at end by [@deseo] in #1010
title
if jekyll-seo-tag
not in users's plugins by [@Tom-Brouwer] in #1040
favicon.html
, shifts content to head_custom.html
by [@mattxwang] in #1027
reversed
, deprecate desc
for nav child_nav_order
by [@jmertic] in #1061
child.child_nav_order
to node.child_nav_order
by [@mattxwang] in #1065
/
as SASS division by [@mattxwang] in #1074
declaration-block-no-redundant-longhand-properties
by [@simonebortolin] in #1102
padding
property value pair in labels.scss
by [@SConaway] in #1104
<svg>
icons by [@captn3m0] in #1110
jekyll-anchor-headings
, lunr.js
by [@mattxwang] in #1071
_
-prefix for collections by [@max06] in #1091
Full Changelog: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc3...v0.4.0.rc4
Hi there! This is (actually) hopefully the last prerelease before v0.4.0
; in particular, if we find that this prerelease is stable, we'll re-release it as v0.4.0
.
In general, this is a more mature pre-release; there are few new features. However, we'll highlight @pdmosses's work in #992 to better optimize nav generation for large sites (ex 100+ pages). We don't expect this to affect most users; however, it is technically a breaking change, and we suggest testing your site before upgrading to this prerelease.
We want your feedback! Please open an issue or start a discussion and let us know!
As soon as we get stable test results from major downstream users, we'll push out a v0.4.0
ASAP - closing out almost 2 years of backlogged work!
v0.4.0.rc3
Simlar to the prior release, v0.4.0.rc3
is a release candidate for the theme (i.e., a pre-release) with release v0.4.0
coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to v0.4.0.rc3
.
To use this RC explicitly as a remote theme:
remote_theme: just-the-docs/[email protected]
To use this RC explicitly as a gem-based theme, pin the version in your Gemfile
and re-run bundle install
or bundle update just-the-docs
:
gem "just-the-docs", "0.4.0.rc3"
By default, users will not be upgraded to 0.4.0.rc3
. To enforce that explicitly, either:
Gemfile
, like sogem "just-the-docs", "0.3.3"
remote_theme
, like soremote_theme: just-the-docs/[email protected]
Broadly, this prerelease is feature-light!
<blockquote>
by @mattxwang in #965
Note: experimental nav optimization may be unstable. Please give us feedback!
text-decoration
values by @mattxwang in #967
Full Changelog: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc2...v0.4.0.rc3
Hey there! This is likely the last pre-release before releasing v0.4.0
, which we plan on doing soon (i.e. before the end of the month) - very exciting! Some new additions to highlight:
The intention of this release candidate is to gather even more feedback on a potential v0.4.0
. As it stands, we have not encountered any breaking changes with early adopters of v0.4.0.rc1
. If you encounter any - for either of our prereleases - please let us know!
v0.4.0.rc2
Simlar to the prior release, v0.4.0.rc2
is a release candidate for the theme (i.e., a pre-release) with release v0.4.0
coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to v0.4.0.rc2
.
To use this RC explicitly as a remote theme:
remote_theme: just-the-docs/[email protected]
To use this RC explicitly as a gem-based theme, pin the version in your Gemfile
and re-run bundle install
or bundle update just-the-docs
:
gem "just-the-docs", "0.4.0.rc2"
By default, users will not be upgraded to 0.4.0.rc2
. To enforce that explicitly, either:
Gemfile
, like sogem "just-the-docs", "0.3.3"
remote_theme
, like soremote_theme: just-the-docs/[email protected]
vendor/
in Jekyll config by @manuelhenke in https://github.com/just-the-docs/just-the-docs/pull/941
Full Changelog: https://github.com/just-the-docs/just-the-docs/compare/v0.4.0.rc1...v0.4.0.rc2
Hi all! The Just the Docs team is excited to have our first pre-release in over two years! It is jam-packed with features and bugfixes that have been requested by the community since 2020. They include:
rake
command, using relative_url
, and search input colorWe want your feedback! Are these changes helpful? Are our docs easy to understand? Should new features like mermaid
be opt-in or opt-out? Please open an issue or start a discussion and let us know!
v0.4.0.rc1
Due to the massive scope of these changes, we're making v0.4.0.rc1
avaialble as a release candidate for the theme (i.e., a pre-release) with release v0.4.0
coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to v0.4.0.rc1
.
To use this RC explicitly as a remote theme:
remote_theme: just-the-docs/[email protected]
To use this RC explicitly as a gem-based theme, pin the version in your Gemfile
and re-run bundle install
or bundle update just-the-docs
:
gem "just-the-docs", "0.4.0.rc1"
v0.3.3
If you're not ready to make the switch, that's alright! If your version of just-the-docs is pinned to v0.3.3
(i.e. by a Gemfile.lock
or in remote_theme
, then there's nothing you need to do.
If you have not pinned your theme version, you should either:
Gemfile
, like sogem "just-the-docs", "0.3.3"
remote_theme
, like soremote_theme: just-the-docs/[email protected]
Warning: Use of branches for closed PRs (e.g., https://github.com/just-the-docs/just-the-docs/pull/466, https://github.com/just-the-docs/just-the-docs/pull/578) is now deprecated, as those branches have been (directly or indirectly) merged, and they will be deleted after the release of v0.4.0.rc1
.
Internally, our maintainer team has expanded: Patrick Marsceill, the original maintainer, has stepped down from an active role after almost 4 years! We're very thankful for the work that he's done to create and maintain one of the most popular Jekyll themes. Please join us in giving him thanks!
The new core team currently consists of @mattxwang, @pdmosses, @skullface, @dougaitken, and @max06. Over the past six months, we've been triaging and merging in PRs, as well as contributing our own fixes. We'll continue to address open issues, merge in PRs from the community, and plan out the future of Just the Docs. If you'd like to contribute, now is a great time!
In the short-term, we're committed to tidying up everything for a v0.4.0
release. This involves fixing bugs reported from the community in this pre-release, as well as continually merging in minor PRs.
We're also scoping out medium and long-term projects, and want to keep you in the loop. These include:
as well as DX improvements like better regression tests, CI, and tooling. If you're interested in any of these, please join us on GitHub - any contribution (raising an issue, writing docs, or submitting a PR) is welcome!
nav_fold
(no PR)absolute_url
by relative_url
, by @svrooij in https://github.com/just-the-docs/just-the-docs/pull/544
_includes
by @burner1024 in https://github.com/just-the-docs/just-the-docs/pull/364
nav_footer_custom
include by @nathanjessen in https://github.com/just-the-docs/just-the-docs/pull/474
mermaid
config to use mermaid_config.js
include, only require mermaid.version
in _config.yml
by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/909
site.collections_dir
if exists by @alexsegura in https://github.com/just-the-docs/just-the-docs/pull/519
overflow-x: auto
to figure.highlight
by @iridazzle in https://github.com/just-the-docs/just-the-docs/pull/727
overflow-wrap: word-break
to body
by @iridazzle in https://github.com/just-the-docs/just-the-docs/pull/889
ol
by @pdmosses in https://github.com/just-the-docs/just-the-docs/pull/856
custom_head
to add a custom favicon by @UnclassedPenguin in https://github.com/just-the-docs/just-the-docs/pull/814
ol
on index.md
by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/778
index.md
by @sehilyi in https://github.com/just-the-docs/just-the-docs/pull/499
index.md
by @nathanjessen in https://github.com/just-the-docs/just-the-docs/pull/473
README
on _config.yml
by @ivanskodje in https://github.com/just-the-docs/just-the-docs/pull/891
webrick
to Gemfile
by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/799
master
-> main
by @pmarsceill in https://github.com/just-the-docs/just-the-docs/pull/776
Full Changelog: https://github.com/just-the-docs/just-the-docs/compare/v0.3.3...v0.4.0.rc1
nav_exclude
to the main navigation @pdmosses (#443)