steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-04-10 14:01:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Clarify version docs (#955)

Browse Source 
This PR updates the home page and the CHANGELOG to refer to  v0.4.0.rc1 as a pre-release or release candidate, rather than a release. See [this comment](https://github.com/just-the-docs/just-the-docs/pull/613#issuecomment-1240442518) for motivation.

It also adds the versioned docs issue (#728) to the roadmap in the CHANGELOG.

As the config for the theme docs now needs to declare callouts, the [callouts docs](https://just-the-docs.github.io/just-the-docs/docs/ui-components/callouts/) can now illustrate the rendered appearance. (These callouts are merely examples: the names and colors should eventually be replaced by a principled collection, taking account of WCAG.)
This commit is contained in:
Peter Mosses 2022-09-11 01:44:27 +02:00 committed by GitHub
parent 3f89145543
commit bd2af37865
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 100 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
CHANGELOG.md
View File

@ -1,10 +1,12 @@
# Changelog
# CHANGELOG
All notable changes to this project are documented in this file.
*Note:* the project underwent a maintenance shift in the creation of v0.4.0.
*Note:* The project underwent a major maintenance shift in March 2022.
## Head
## HEAD
*Note:* This website is built from the `HEAD` of the `main` branch of the theme repository. It includes docs for the following changes, which are *not* in the latest pre-release!
### Changes
@ -17,26 +19,26 @@ All notable changes to this project are documented in this file.
- Fixed: exclude `vendor/` in Jekyll config by @manuelhenke in https://github.com/just-the-docs/just-the-docs/pull/941
- Deleted: unused script directory by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/937
## v0.4.0.rc1
## Pre-release v0.4.0.rc1
### We're back!
Hi all! The Just the Docs team is excited to have our first release in over two years! This release is jam-packed with features and bugfixes that have been requested by the community since 2020. They include:
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:
- The new callouts component
- Allowing pages and collections to coexist on the navigation pane
- New styling: dark syntax highlighting, support for jekyll-asciidoc, word-wrapping instead of overflow for various elements
- More customization: external nav links, custom nav footers, favicon includes, search color and placeholder configuration, mermaid.js support, and nav sorting
- Over 20 bugfixes! Big ones include fixing the `rake` command, using `relative_url`, and search input color
- More documentation, especially on using custom includes.
- More documentation, especially on using custom includes
- Updating core dependencies to stable Ruby versions
- A WIP [template repository](https://github.com/just-the-docs/just-the-docs-template) that allows you to setup your own repository using Just the Docs and GitHub Pages with one click - give it a shot! More documentation, etc. is on the way!
We 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](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know!
### Trying out `v0.4.0.rc1`
### Trying out pre-release `v0.4.0.rc1`
Due to the massive scope of these changes, we're releasing `v0.4.0.rc1` as a **release candidate** for the theme, with `v0.4.0` coming soon. We want your help in testing the theme! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1` - if your version of Just the Docs is not pinned, you'll see the changes the next time you build / run `bundle install` (if you don't use a `Gemfile.lock`) or `bundle update just-the-docs` (if you do).
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` - if your version of Just the Docs is not pinned, you'll see the changes the next time you run `bundle install` (if you don't have a `Gemfile.lock`) or `bundle update just-the-docs` (if you do).
To use this RC explicitly as a remote theme:
@ -44,7 +46,7 @@ To use this RC explicitly as a remote theme:
remote_theme: just-the-docs/just-the-docs@v0.4.0.rc1
```
To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install`:
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`:
```Ruby
gem "just-the-docs", "0.4.0.rc1"
@ -75,11 +77,12 @@ The new core team currently consists of @mattxwang, @pdmosses, @skullface, @doug
### Roadmap
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 release, as well as continually merging in minor PRs.
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:
- upgrading to Jekyll 4, and stopping support for Jekyll 3
- versioned docs - issue [#728](https://github.com/just-the-docs/just-the-docs/issues/728)
- improved accessibility - issues [#566](https://github.com/just-the-docs/just-the-docs/issues/566), [#870](https://github.com/just-the-docs/just-the-docs/issues/870)
- internationalization (i18n) - issue [#59](https://github.com/just-the-docs/just-the-docs/issues/59)
- recursive/multi-level navigation - PR [#462](https://github.com/just-the-docs/just-the-docs/pull/462)

17
_config.yml
View File

@ -107,6 +107,23 @@ gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into t
# Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
color_scheme: nil
callouts_level: quiet # or loud
callouts:
highlight:
color: yellow
important:
title: Important
color: blue
new:
title: New
color: green
note:
title: Note
color: purple
warning:
title: Warning
color: red
# Google Analytics Tracking (optional)
# e.g, UA-1234567-89
ga_tracking: UA-2709176-10

59
docs/ui-components/callouts.md
View File

@ -9,7 +9,10 @@ nav_order: 7
Markdown does not include support for callouts. However, you can style text as a callout using a Markdown extension supported by kramdown: [*block IALs*](https://kramdown.gettalong.org/quickref.html#block-attributes).
Common kinds of callouts include `admonition`, `attention`, `caution`, `danger`, `error`, `hint`, `important`, `note`, `tip`, and `warning`.
Common kinds of callouts include `highlight`, `important`, `new`, `note`, and `warning`.
{: .warning }
These callout names are *not* pre-defined by the theme: you need to define your own names.
When you have [configured]({{ site.baseurl }}{% link docs/configuration.md %}#callouts) the `color` and (optional) `title` for a callout, you can apply it to a paragraph, or to a block quote with several paragraphs, as illustrated below.[^postfix]
@ -24,6 +27,10 @@ When you have [configured]({{ site.baseurl }}{% link docs/configuration.md %}#ca
A paragraph
```
{: .highlight }
A paragraph
#### A single paragraph callout
{: .no_toc }
@ -32,6 +39,9 @@ A paragraph
A paragraph
```
{: .note }
A paragraph
```markdown
{: .note-title }
> My note title
@ -39,6 +49,11 @@ A paragraph
> A paragraph with a custom title callout
```
{: .note-title }
> My note title
>
> A paragraph with a custom title callout
#### A multi-paragraph callout
{: .no_toc }
@ -51,6 +66,13 @@ A paragraph
> The last paragraph
```
{: .important }
> A paragraph
>
> Another paragraph
>
> The last paragraph
```markdown
{: .important-title }
> My important title
@ -62,19 +84,31 @@ A paragraph
> The last paragraph
```
{: .important-title }
> My important title
>
> A paragraph
>
> Another paragraph
>
> The last paragraph
#### An indented callout
{: .no_toc }
```markdown
> {: .hint }
> {: .highlight }
A paragraph
```
> {: .highlight }
A paragraph
#### Indented multi-paragraph callouts
{: .no_toc }
```markdown
> {: .attention }
> {: .new }
> > A paragraph
> >
> > Another paragraph
@ -82,6 +116,14 @@ A paragraph
> > The last paragraph
```
> {: .new }
> > A paragraph
> >
> > Another paragraph
> >
> > The last paragraph
#### Nested callouts
{: .no_toc }
@ -91,6 +133,10 @@ A paragraph
> A paragraph
```
{: .important }
> {: .warning }
> A paragraph
#### Opaque background
{: .no_toc }
@ -102,3 +148,10 @@ A paragraph
> A paragraph
> </div>
```
{: .important }
> {: .opaque }
> <div markdown="block">
> {: .warning }
> A paragraph
> </div>

15
index.md
View File

@ -16,7 +16,20 @@ Just the Docs gives your documentation a jumpstart with a responsive Jekyll them
---
**New: version `0.4.0.rc1` has just been released! See [the changelog](https://github.com/just-the-docs/just-the-docs/blob/main/CHANGELOG.md) for a detailed breakdown!**
{: .new }
> **Pre-release version `0.4.0.rc1` is available!**
> See [the CHANGELOG](https://github.com/just-the-docs/just-the-docs/blob/main/CHANGELOG.md) for a detailed breakdown.
{: .warning }
> Specifying `gem "just-the-docs"` in your `Gemfile` uses the latest ***release*** (`v0.3.3`), ignoring all pre-releases!
> To use this pre-release, pin it:
> ```ruby
> gem "just-the-docs", "0.4.0.rc1"
> ```
> and/or
> ```yaml
> remote_theme: just-the-docs/just-the-docs@v0.4.0.rc1
> ```
## Getting started