mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-22 02:52:23 -06:00
bd2af37865
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.)
119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
---
|
||
layout: default
|
||
title: Home
|
||
nav_order: 1
|
||
description: "Just the Docs is a responsive Jekyll theme with built-in search that is easily customizable and hosted on GitHub Pages."
|
||
permalink: /
|
||
---
|
||
|
||
# Focus on writing good documentation.
|
||
{: .fs-9 }
|
||
|
||
Just the Docs gives your documentation a jumpstart with a responsive Jekyll theme that is easily customizable and hosted on GitHub Pages.
|
||
{: .fs-6 .fw-300 }
|
||
|
||
[Get started now](#getting-started){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } [View it on GitHub](https://github.com/just-the-docs/just-the-docs){: .btn .fs-5 .mb-4 .mb-md-0 }
|
||
|
||
---
|
||
|
||
{: .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
|
||
|
||
### Dependencies
|
||
|
||
Just the Docs is built for [Jekyll](https://jekyllrb.com), a static site generator. View the [Jekyll quick start guide](https://jekyllrb.com/docs/) for more information. Just the Docs requires no special plugins and can run on GitHub Pages' standard Jekyll compiler. The [Jekyll SEO Tag plugin](https://github.com/jekyll/jekyll-seo-tag) is included by default (no need to run any special installation) to inject SEO and open graph metadata on docs pages. For information on how to configure SEO and open graph metadata visit the [Jekyll SEO Tag usage guide](https://jekyll.github.io/jekyll-seo-tag/usage/).
|
||
|
||
### Quick start: Use as a GitHub Pages remote theme
|
||
|
||
1. Add Just the Docs to your Jekyll site's `_config.yml` as a [remote theme](https://blog.github.com/2017-11-29-use-any-theme-with-github-pages/)
|
||
|
||
```yaml
|
||
remote_theme: just-the-docs/just-the-docs
|
||
```
|
||
|
||
<small>You must have GitHub Pages enabled on your repo, one or more Markdown files, and a `_config.yml` file. [See an example repository](https://github.com/pmarsceill/jtd-remote)</small>
|
||
|
||
### Local installation: Use the gem-based theme
|
||
|
||
1. Install the Ruby Gem
|
||
```bash
|
||
$ gem install just-the-docs
|
||
```
|
||
```yaml
|
||
# .. or add it to your Jekyll site’s Gemfile
|
||
gem "just-the-docs"
|
||
```
|
||
|
||
2. Add Just the Docs to your Jekyll site’s `_config.yml`
|
||
```yaml
|
||
theme: "just-the-docs"
|
||
```
|
||
|
||
3. _Optional:_ Initialize search data (creates `search-data.json`)
|
||
```bash
|
||
$ bundle exec just-the-docs rake search:init
|
||
```
|
||
|
||
3. Run your local Jekyll server
|
||
```bash
|
||
$ jekyll serve
|
||
```
|
||
```bash
|
||
# .. or if you're using a Gemfile (bundler)
|
||
$ bundle exec jekyll serve
|
||
```
|
||
|
||
|
||
4. Point your web browser to [http://localhost:4000](http://localhost:4000)
|
||
|
||
If you're hosting your site on GitHub Pages, [set up GitHub Pages and Jekyll locally](https://help.github.com/en/articles/setting-up-your-github-pages-site-locally-with-jekyll) so that you can more easily work in your development environment.
|
||
|
||
### Configure Just the Docs
|
||
|
||
- [See configuration options]({{ site.baseurl }}{% link docs/configuration.md %})
|
||
|
||
---
|
||
|
||
## About the project
|
||
|
||
Just the Docs is © 2017-{{ "now" | date: "%Y" }} by [Patrick Marsceill](http://patrickmarsceill.com).
|
||
|
||
### License
|
||
|
||
Just the Docs is distributed by an [MIT license](https://github.com/just-the-docs/just-the-docs/tree/main/LICENSE.txt).
|
||
|
||
### Contributing
|
||
|
||
When contributing to this repository, please first discuss the change you wish to make via issue,
|
||
email, or any other method with the owners of this repository before making a change. Read more about becoming a contributor in [our GitHub repo](https://github.com/just-the-docs/just-the-docs#contributing).
|
||
|
||
#### Thank you to the contributors of Just the Docs!
|
||
|
||
<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>
|
||
|
||
### Code of Conduct
|
||
|
||
Just the Docs is committed to fostering a welcoming community.
|
||
|
||
[View our Code of Conduct](https://github.com/just-the-docs/just-the-docs/tree/main/CODE_OF_CONDUCT.md) on our GitHub repository.
|