diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 8efd188d4c3c487184bd605e3f89c347d0cbfe85..fd77ad0a8fa6d2cf09a5a869d86d426261c3a9e0 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,5 @@ blank_issues_enabled: false contact_links: - name: Ask a question - url: https://github.com/pmarsceill/just-the-docs/discussions + url: https://github.com/just-the-docs/just-the-docs/discussions about: Ask questions and discuss with other community members diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index bdfde2a0eaa2b6a85494f07775e56a275798a51f..6a1034e28eddb31e7eddde9d1fdb067976085577 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -1,33 +1,33 @@ references: - v+ - - master -name-template: 'v$RESOLVED_VERSION 🌈' -tag-template: 'v$RESOLVED_VERSION' + - main +name-template: "v$RESOLVED_VERSION 🌈" +tag-template: "v$RESOLVED_VERSION" categories: - - title: '🚀 Features' + - title: "🚀 Features" labels: - - 'feature' - - 'enhancement' - - title: '🛠Bug Fixes' + - "feature" + - "enhancement" + - title: "🛠Bug Fixes" labels: - - 'fix' - - 'bugfix' - - 'bug' - - title: '🧰 Maintenance' - label: - - 'chore' - - 'dependencies' -change-template: '- $TITLE @$AUTHOR (#$NUMBER)' + - "fix" + - "bugfix" + - "bug" + - title: "🧰 Maintenance" + label: + - "chore" + - "dependencies" +change-template: "- $TITLE @$AUTHOR (#$NUMBER)" version-resolver: major: labels: - - 'next-major-release' + - "next-major-release" minor: labels: - - 'next-minor-release' + - "next-minor-release" patch: labels: - - 'patch' + - "patch" default: minor template: | ## Changes diff --git a/.github/workflows/ci-master.yml b/.github/workflows/ci-master.yml index 6d41eb596a0919cbf7f87454616697d008185ed9..4f970d4cfc4612b394cf40b8bd202020aea09783 100644 --- a/.github/workflows/ci-master.yml +++ b/.github/workflows/ci-master.yml @@ -1,45 +1,42 @@ -on: +on: push: branches: - - master + - main -name: Master branch CI +name: main branch CI jobs: - jekyll-latest: name: Build Jekyll site (latest) runs-on: ubuntu-latest steps: + - uses: actions/checkout@main - - uses: actions/checkout@master - - - name: Build the site in the jekyll/builder container - run: | - docker run --rm \ - --volume="${{ github.workspace }}:/srv/jekyll" \ - jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init" + - name: Build the site in the jekyll/builder container + run: | + docker run --rm \ + --volume="${{ github.workspace }}:/srv/jekyll" \ + jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init" jekyll-3-8-5: name: Build Jekyll site (v3.8.5) runs-on: ubuntu-latest steps: + - uses: actions/checkout@main - - uses: actions/checkout@master - - - name: Build the site in the jekyll/builder container - run: | - docker run --rm \ - --volume="${{ github.workspace }}:/srv/jekyll" \ - jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init" + - name: Build the site in the jekyll/builder container + run: | + docker run --rm \ + --volume="${{ github.workspace }}:/srv/jekyll" \ + jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init" assets: name: Format and test CSS and JS runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - name: Use Node.js 12.x - uses: actions/setup-node@v1 - with: - node-version: '12.x' - - run: npm install - - run: npm test + - uses: actions/checkout@v2 + - name: Use Node.js 12.x + uses: actions/setup-node@v1 + with: + node-version: "12.x" + - run: npm install + - run: npm test diff --git a/.prettierignore b/.prettierignore index 5dc073f5a8f3aa8fdb28879e48ca68cc8e76a7e7..692aa342ebface613fa395bb6205ffcef614b16b 100644 --- a/.prettierignore +++ b/.prettierignore @@ -7,3 +7,4 @@ assets/css/just-the-docs-dark.scss assets/js/vendor/lunr.min.js assets/js/search-data.json assets/js/just-the-docs.js +*.md diff --git a/.prettierrc b/.prettierrc index 284e842b027a9ef2501ce69f31bb09e5297b8f60..70175ce150ccda1fc61eeb3f4ba4308438ca8cb6 100644 --- a/.prettierrc +++ b/.prettierrc @@ -4,5 +4,4 @@ "singleQuote": false, "tabWidth": 2, "trailingComma": "es5" -} - +} \ No newline at end of file diff --git a/README.md b/README.md index 4d1c1e889f5d6e5aaac95ed0899d7ec42c3a559f..019a7415523b69773cef93a8096bb70ec84567d3 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ <p align="right"> - <a href="https://badge.fury.io/rb/just-the-docs"><img src="https://badge.fury.io/rb/just-the-docs.svg" alt="Gem version"></a> <a href="https://github.com/pmarsceill/just-the-docs/actions?query=workflow%3A%22Master+branch+CI%22"><img src="https://github.com/pmarsceill/just-the-docs/workflows/Master%20branch%20CI/badge.svg" alt="Build status"></a> + <a href="https://badge.fury.io/rb/just-the-docs"><img src="https://badge.fury.io/rb/just-the-docs.svg" alt="Gem version"></a> <a href="https://github.com/just-the-docs/just-the-docs/actions?query=workflow%3A%22main+branch+CI%22"><img src="https://github.com/just-the-docs/just-the-docs/workflows/main%20branch%20CI/badge.svg" alt="Build status"></a> </p> <br><br> <p align="center"> <h1 align="center">Just the Docs</h1> <p align="center">A modern, highly customizable, and responsive Jekyll theme for documentation with built-in search.<br>Easily hosted on GitHub Pages with few dependencies.</p> - <p align="center"><strong><a href="https://pmarsceill.github.io/just-the-docs/">See it in action!</a></strong></p> + <p align="center"><strong><a href="https://just-the-docs.github.io/just-the-docs/">See it in action!</a></strong></p> <br><br><br> </p> @@ -13,6 +13,17 @@ ## Installation +### via GitHub Pages remote theme + +The quickiest way to use Just The Docs is to use GitHub pages [remote theme](https://blog.github.com/2017-11-29-use-any-theme-with-github-pages/) feature in your `config.yml` file: + +```yaml +remote_theme: just-the-docs/just-the-docs +``` +### via RubyGems: + +Alternatively you can install it as a Ruby Gem. + Add this line to your Jekyll site's Gemfile: ```ruby @@ -39,15 +50,15 @@ Alternatively, you can run it inside Docker while developing your site ## Usage -[View the documentation](https://pmarsceill.github.io/just-the-docs/) for usage information. +[View the documentation](https://just-the-docs.github.io/just-the-docs/) for usage information. ## Contributing -Bug reports and pull requests are welcome on GitHub at https://github.com/pmarsceill/just-the-docs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. +Bug reports and pull requests are welcome on GitHub at https://github.com/just-the-docs/just-the-docs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. ### Submitting code changes: -- Open a [Pull Request](https://github.com/pmarsceill/just-the-docs/pulls) +- Open a [Pull Request](https://github.com/just-the-docs/just-the-docs/pulls) - Ensure all CI tests pass - Await code review - Bump the version number in `just-the-docs.gemspec` and `package.json` according to [semantic versioning](https://semver.org/). diff --git a/_config.yml b/_config.yml index ad42809851c16e11931ccd89a1f61643cb245d47..dbe742f2f73981f43aa3f2c8d41b19fc4e595591 100644 --- a/_config.yml +++ b/_config.yml @@ -16,7 +16,7 @@ title: Just the Docs description: A Jekyll theme for documentation baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog -url: "https://pmarsceill.github.io" # the base hostname & protocol for your site, e.g. http://example.com +url: "https://just-the-docs.github.io" # the base hostname & protocol for your site, e.g. http://example.com permalink: pretty exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json", "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile" @@ -65,7 +65,7 @@ heading_anchors: true # Aux links for the upper right navigation aux_links: "Just the Docs on GitHub": - - "//github.com/pmarsceill/just-the-docs" + - "//github.com/just-the-docs/just-the-docs" # Makes Aux links open in a new tab. Default is false aux_links_new_tab: false @@ -81,7 +81,7 @@ nav_sort: case_sensitive # Capital letters sorted before lowercase back_to_top: true back_to_top_text: "Back to top" -footer_content: "Copyright © 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt\">MIT license.</a>" +footer_content: "Copyright © 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/just-the-docs/just-the-docs/tree/main/LICENSE.txt\">MIT license.</a>" # Footer last edited timestamp last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter @@ -92,8 +92,8 @@ last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https:/ # Footer "Edit this page on GitHub" link text gh_edit_link: true # show or hide edit this page link gh_edit_link_text: "Edit this page on GitHub" -gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo -gh_edit_branch: "master" # the branch that your docs is served from +gh_edit_repository: "https://github.com/just-the-docs/just-the-docs" # the github URL for your repo +gh_edit_branch: "main" # the branch that your docs is served from # gh_edit_source: docs # the source that your files originate from gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately diff --git a/_layouts/default.html b/_layouts/default.html index f571923c091698a84f8ec5103b60e81733a76318..40d85ace46e5e2c9468f608877adef51988245f8 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -66,7 +66,7 @@ layout: table_wrappers {% endif %} </nav> <footer class="site-footer"> - This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll. + This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll. </footer> </div> <div class="main" id="top"> diff --git a/docs/configuration.md b/docs/configuration.md index 7b21bfab759aad921c3a5bd2fd0eb17510074e79..b11f448fe0c462aa707ce181ea42071e68f13b9a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -7,8 +7,7 @@ nav_order: 2 # Configuration {: .no_toc } - -Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's _config.yml file. +Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's \_config.yml file. {: .fs-6 .fw-300 } ## Table of contents @@ -19,9 +18,7 @@ Just the Docs has some specific configuration parameters that can be defined in --- - -View this site's [_config.yml](https://github.com/pmarsceill/just-the-docs/tree/master/_config.yml) file as an example. - +View this site's [\_config.yml](https://github.com/just-the-docs/just-the-docs/tree/main/_config.yml) file as an example. ## Site logo @@ -68,7 +65,7 @@ search: # Aux links for the upper right navigation aux_links: "Just the Docs on GitHub": - - "//github.com/pmarsceill/just-the-docs" + - "//github.com/just-the-docs/just-the-docs" # Makes Aux links open in a new tab. Default is false aux_links_new_tab: false @@ -91,7 +88,7 @@ heading_anchors: true # appears at the bottom of every page's main content # Note: The footer_content option is deprecated and will be removed in a future major release. Please use `_includes/footer_custom.html` for more robust markup / liquid-based content. -footer_content: "Copyright © 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt\">MIT license.</a>" +footer_content: "Copyright © 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/just-the-docs/just-the-docs/tree/main/LICENSE.txt\">MIT license.</a>" # Footer last edited timestamp last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter @@ -100,8 +97,8 @@ last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https:/ # Footer "Edit this page on GitHub" link text gh_edit_link: true # show or hide edit this page link gh_edit_link_text: "Edit this page on GitHub." -gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo -gh_edit_branch: "master" # the branch that your docs is served from +gh_edit_repository: "https://github.com/just-the-docs/just-the-docs" # the github URL for your repo +gh_edit_branch: "main" # the branch that your docs is served from # gh_edit_source: docs # the source that your files originate from gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately ``` @@ -111,7 +108,7 @@ _note: `footer_content` is deprecated, but still supported. For a better experie - the "page last modified" data will only display if a page has a key called `last_modified_date`, formatted in some readable date format - `last_edit_time_format` uses Ruby's DateTime formatter; see examples and more information [at this link.](https://apidock.com/ruby/DateTime/strftime) - `gh_edit_repository` is the URL of the project's GitHub repository -- `gh_edit_branch` is the branch that the docs site is served from; defaults to `master` +- `gh_edit_branch` is the branch that the docs site is served from; defaults to `main` - `gh_edit_source` is the source directory that your project files are stored in (should be the same as [site.source](https://jekyllrb.com/docs/configuration/options/)) - `gh_edit_view_mode` is `"tree"` by default, which brings the user to the github page; switch to `"edit"` to bring the user directly into editing mode @@ -121,6 +118,7 @@ _note: `footer_content` is deprecated, but still supported. For a better experie # Color scheme supports "light" (default) and "dark" color_scheme: dark ``` + <button class="btn js-toggle-dark-mode">Preview dark color scheme</button> <script> @@ -154,6 +152,7 @@ By default, the navigation and search include normal [pages](https://jekyllrb.co Instead, you can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together. For example, put all your documentation files in the `_docs` folder and create the `docs` collection: + ```yaml # Define Jekyll collections collections: @@ -179,6 +178,7 @@ just_the_docs: You can reference multiple collections. This creates categories in the navigation with the configured names. + ```yaml collections: docs: @@ -195,4 +195,3 @@ just_the_docs: tutorials: name: Tutorials ``` - diff --git a/docs/customization.md b/docs/customization.md index cbcd38cc1c1350e95573be81ac1ec5384aa8bc1a..075e30d9a957ea43df1b051a806fd2de99d71e73 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -16,6 +16,7 @@ nav_order: 6 --- ## Color schemes + {: .d-inline-block } New @@ -32,6 +33,7 @@ To enable a color scheme, set the `color_scheme` parameter in your site's `_conf # Color scheme supports "light" (default) and "dark" color_scheme: dark ``` + <button class="btn js-toggle-dark-mode">Preview dark color scheme</button> <script> @@ -53,10 +55,10 @@ jtd.addEvent(toggleDarkMode, 'click', function(){ ### Define a custom scheme You can add custom schemes. -If you want to add a scheme named `foo` (can be any name) just add a file `_sass/color_schemes/foo.scss` (replace `foo` by your scheme name) +If you want to add a scheme named `foo` (can be any name) just add a file `_sass/color_schemes/foo.scss` (replace `foo` by your scheme name) where you override theme variables to change colors, fonts, spacing, etc. -Available variables are listed in the [_variables.scss](https://github.com/pmarsceill/just-the-docs/tree/master/_sass/support/_variables.scss) file. +Available variables are listed in the [\_variables.scss](https://github.com/just-the-docs/just-the-docs/tree/main/_sass/support/_variables.scss) file. For example, to change the link color from the purple default to blue, include the following inside your scheme file: @@ -73,6 +75,7 @@ Please use scheme files. ### Use a custom scheme To use the custom color scheme, only set the `color_scheme` parameter in your site's `_config.yml` file: + ```yaml color_scheme: foo ``` @@ -80,7 +83,7 @@ color_scheme: foo ### Switchable custom scheme If you want to be able to change the scheme dynamically, for example via javascript, just add a file `assets/css/just-the-docs-foo.scss` (replace `foo` by your scheme name) -with the following content:` +with the following content: {% raw %} --- @@ -91,7 +94,7 @@ with the following content:` This allows you to switch the scheme via the following javascript. ```js -jtd.setTheme('foo'); +jtd.setTheme("foo") ``` ## Override and completely custom styles @@ -109,7 +112,13 @@ For example, if you'd like to add your own styles for printing a page, you could ```scss // Print-only styles. @media print { - .side-bar, .page-header { display: none; } - .main-content { max-width: auto; margin: 1em;} + .side-bar, + .page-header { + display: none; + } + .main-content { + max-width: auto; + margin: 1em; + } } ``` diff --git a/docs/navigation-structure.md b/docs/navigation-structure.md index 893a9b8feb161e102fa7a8623a0acf81add59dbd..535a2e0ee7daa606b1b1774b03bfa8f9887791a4 100644 --- a/docs/navigation-structure.md +++ b/docs/navigation-structure.md @@ -5,6 +5,7 @@ nav_order: 5 --- # Navigation Structure + {: .no_toc } <details open markdown="block"> @@ -31,6 +32,7 @@ By default, all pages will appear as top level pages in the main nav unless a pa To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter. #### Example + {: .no_toc } ```yaml @@ -39,6 +41,7 @@ layout: default title: Customization nav_order: 4 --- + ``` The parameter values determine the order of the top-level pages, and of child pages with the same parent. You can reuse the same parameter values (e.g., integers starting from 1) for the child pages of different parents. @@ -47,7 +50,7 @@ The parameter values can be numbers (integers, floats) and/or strings. When you By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case. Enclosing strings in quotation marks is optional. -> *Note for users of previous versions:* `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated. +> _Note for users of previous versions:_ `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated. --- @@ -56,6 +59,7 @@ By default, all Capital letters come before all lowercase letters; you can add ` For specific pages that you do not wish to include in the main navigation, e.g. a 404 page or a landing page, use the `nav_exclude: true` parameter in the YAML front matter for that page. #### Example + {: .no_toc } ```yaml @@ -64,11 +68,12 @@ layout: default title: 404 nav_exclude: true --- + ``` The `nav_exclude` parameter does not affect the [auto-generating list of child pages](#auto-generating-table-of-contents), which you can use to access pages excluded from the main navigation. -Pages with no `title` are automatically excluded from the navigation. +Pages with no `title` are automatically excluded from the navigation. --- @@ -104,9 +109,11 @@ Sometimes you will want to create a page with many children (a section). First, ``` On the parent pages, add this YAML front matter parameter: -- `has_children: true` (tells us that this is a parent page) + +- `has_children: true` (tells us that this is a parent page) #### Example + {: .no_toc } ```yaml @@ -116,16 +123,19 @@ title: UI Components nav_order: 2 has_children: true --- + ``` Here we're setting up the UI Components landing page that is available at `/docs/ui-components`, which has children and is ordered second in the main nav. ### Child pages + {: .text-gamma } On child pages, simply set the `parent:` YAML front matter to whatever the parent's page title is and set a nav order (this number is now scoped within the section). #### Example + {: .no_toc } ```yaml @@ -135,6 +145,7 @@ title: Buttons parent: UI Components nav_order: 2 --- + ``` The Buttons page appears as a child of UI Components and appears second in the UI Components section. @@ -144,6 +155,7 @@ The Buttons page appears as a child of UI Components and appears second in the U By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set `has_toc: false` in the parent page's YAML front matter. #### Example + {: .no_toc } ```yaml @@ -154,9 +166,11 @@ nav_order: 2 has_children: true has_toc: false --- + ``` ### Children with children + {: .text-gamma } Child pages can also have children (grandchildren). This is achieved by using a similar pattern on the child and grandchild pages. @@ -165,6 +179,7 @@ Child pages can also have children (grandchildren). This is achieved by using a 1. Add the `parent` and `grand_parent` attribute to the grandchild #### Example + {: .no_toc } ```yaml @@ -175,6 +190,7 @@ parent: UI Components nav_order: 2 has_children: true --- + ``` ```yaml @@ -185,6 +201,7 @@ parent: Buttons grand_parent: UI Components nav_order: 1 --- + ``` This would create the following navigation structure: @@ -210,13 +227,14 @@ This would create the following navigation structure: To add auxiliary links to your site (in the upper right on all pages), add it to the `aux_links` [configuration option]({{ site.baseurl }}{% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file. #### Example + {: .no_toc } ```yaml # Aux links for the upper right navigation aux_links: "Just the Docs on GitHub": - - "//github.com/pmarsceill/just-the-docs" + - "//github.com/just-the-docs/just-the-docs" ``` --- @@ -226,20 +244,23 @@ aux_links: To generate a Table of Contents on your docs pages, you can use the `{:toc}` method from Kramdown, immediately after an `<ol>` in Markdown. This will automatically generate an ordered list of anchor links to various sections of the page based on headings and heading levels. There may be occasions where you're using a heading and you don't want it to show up in the TOC, so to skip a particular heading use the `{: .no_toc }` CSS class. #### Example + {: .no_toc } ```markdown # Navigation Structure + {: .no_toc } ## Table of contents + {: .no_toc .text-delta } 1. TOC -{:toc} + {:toc} ``` -This example skips the page name heading (`#`) from the TOC, as well as the heading for the Table of Contents itself (`##`) because it is redundant, followed by the table of contents itself. To get an unordered list, replace `1. TOC` above by `- TOC`. +This example skips the page name heading (`#`) from the TOC, as well as the heading for the Table of Contents itself (`##`) because it is redundant, followed by the table of contents itself. To get an unordered list, replace `1. TOC` above by `- TOC`. ### Collapsible Table of Contents diff --git a/docs/search.md b/docs/search.md index 495884df3e5987437361c5c143776c2f1d221c26..69bd106741c849f3e2a411a38d5a07a2ad217372 100644 --- a/docs/search.md +++ b/docs/search.md @@ -5,13 +5,15 @@ nav_order: 7 --- # Search + {: .no_toc } ## Table of contents + {: .no_toc .text-delta } 1. TOC -{:toc} + {:toc} --- @@ -76,7 +78,7 @@ To allow search for hyphenated words: search.tokenizer_separator: /[\s/]+/ ``` -### Display URL in search results +### Display URL in search results ```yaml # Display the relative url in search results @@ -94,13 +96,13 @@ The search button displays in the bottom right corner of the screen and triggers search.button: true ``` - ## Hiding pages from search Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g, a 404 page. To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter: #### Example + {: .no_toc } ```yaml @@ -110,8 +112,8 @@ title: Page not found nav_exclude: true search_exclude: true --- -``` +``` ## Generate search index when used as a gem @@ -124,4 +126,4 @@ $ bundle exec just-the-docs rake search:init ``` This command creates the `assets/js/zzzz-search-data.json` file that Jekyll uses to create your search index. -Alternatively, you can create the file manually with [this content]({{ site.github.repository_url }}/blob/master/assets/js/zzzz-search-data.json). +Alternatively, you can create the file manually with [this content]({{ site.github.repository_url }}/blob/main/assets/js/zzzz-search-data.json). diff --git a/index.md b/index.md index fc2b70987419b3b507a4c2d2f3b7aa6c94290a9a..eb63805ac5edc6a3a280e04aacf451a68f9c2921 100644 --- a/index.md +++ b/index.md @@ -6,13 +6,13 @@ description: "Just the Docs is a responsive Jekyll theme with built-in search th permalink: / --- -# Focus on writing good documentation +# 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/pmarsceill/just-the-docs){: .btn .fs-5 .mb-4 .mb-md-0 } +[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 } --- @@ -25,37 +25,43 @@ Just the Docs is built for [Jekyll](https://jekyllrb.com), a static site generat ### 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: pmarsceill/just-the-docs +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 your Jekyll site’s Gemfile -gem "just-the-docs" -``` + ```bash + $ gem install just-the-docs + ``` + ```yaml + # .. or add it to your 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" -``` + ```yaml + theme: "just-the-docs" + ``` + 3. _Optional:_ Initialize search data (creates `search-data.json`) -```bash -$ bundle exec just-the-docs rake search:init -``` + ```bash + $ bundle exec just-the-docs rake search:init + ``` + 3. Run you local Jekyll server -```bash -$ jekyll serve -``` -```bash -# .. or if you're using a Gemfile (bundler) -$ bundle exec jekyll serve -``` + ```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. @@ -72,12 +78,12 @@ Just the Docs is © 2017-{{ "now" | date: "%Y" }} by [Patrick Marsceill](htt ### License -Just the Docs is distributed by an [MIT license](https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt). +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/pmarsceill/just-the-docs#contributing). +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! @@ -93,4 +99,4 @@ email, or any other method with the owners of this repository before making a ch Just the Docs is committed to fostering a welcoming community. -[View our Code of Conduct](https://github.com/pmarsceill/just-the-docs/tree/master/CODE_OF_CONDUCT.md) on our GitHub repository. +[View our Code of Conduct](https://github.com/just-the-docs/just-the-docs/tree/main/CODE_OF_CONDUCT.md) on our GitHub repository. diff --git a/just-the-docs.gemspec b/just-the-docs.gemspec index 6d467e23e23dbbb7700179f094e7ac5742eb15af..b1ba7bc9fa46a82b4463564d7f12a2d80ea6a5b4 100644 --- a/just-the-docs.gemspec +++ b/just-the-docs.gemspec @@ -7,13 +7,13 @@ Gem::Specification.new do |spec| spec.email = ["patrick.marsceill@gmail.com"] spec.summary = %q{A modern, highly customizable, and responsive Jekyll theme for documention with built-in search.} - spec.homepage = "https://github.com/pmarsceill/just-the-docs" + spec.homepage = "https://github.com/just-the-docs/just-the-docs" spec.license = "MIT" spec.files = `git ls-files -z`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README)}i) } spec.executables << 'just-the-docs' - spec.add_development_dependency "bundler", "~> 2.1.4" + spec.add_development_dependency "bundler", "~> 2.3.5" spec.add_runtime_dependency "jekyll", ">= 3.8.5" spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.0" spec.add_runtime_dependency "rake", ">= 12.3.1", "< 13.1.0" diff --git a/package.json b/package.json index 0f5820439d5ff3bb941e2d4e7c9c0b73177e5ddd..fd320cc7d52ee2d086f319ce4453e15a886e5766 100644 --- a/package.json +++ b/package.json @@ -2,9 +2,9 @@ "name": "just-the-docs", "version": "0.3.3", "description": "A modern Jekyll theme for documentation", - "repository": "pmarsceill/just-the-docs", + "repository": "just-the-docs/just-the-docs", "license": "MIT", - "bugs": "https://github.com/pmarsceill/just-the-docs/issues", + "bugs": "https://github.com/just-the-docs/just-the-docs/issues", "devDependencies": { "stylelint": "^13.7.2", "@primer/css": "^15.2.0",