diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 8efd188..fd77ad0 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 bdfde2a..6a1034e 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 6d41eb5..4f970d4 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/.github/workflows/publish.yml b/.github/workflows/publish-gem.yml similarity index 60% rename from .github/workflows/publish.yml rename to .github/workflows/publish-gem.yml index bba33db..3f1943e 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish-gem.yml @@ -1,30 +1,31 @@ -name: Publish Gem +name: Publish Ruby Gem -on: [release] +on: + workflow_dispatch jobs: build: - name: Build + Publish + name: Publish runs-on: ubuntu-latest steps: - - uses: actions/checkout@master + - uses: actions/checkout@v2 - name: Set up Ruby 2.6 uses: actions/setup-ruby@v1 with: - version: 2.6.x + ruby-version: 2.6.x - name: Publish to GPR run: | mkdir -p $HOME/.gem touch $HOME/.gem/credentials chmod 0600 $HOME/.gem/credentials - printf -- "---\n:github: Bearer ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials - gem build just-the-docs.gemspec + printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials + gem build *.gemspec gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem env: - GEM_HOST_API_KEY: ${{secrets.GPR_AUTH_TOKEN}} - OWNER: pmarsceill + GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}" + OWNER: ${{ github.repository_owner }} - name: Publish to RubyGems run: | @@ -32,8 +33,7 @@ jobs: touch $HOME/.gem/credentials chmod 0600 $HOME/.gem/credentials printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials - gem build just-the-docs.gemspec + gem build *.gemspec gem push *.gem env: - GEM_HOST_API_KEY: ${{secrets.RUBYGEMS_AUTH_TOKEN}} - + GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}" diff --git a/.prettierignore b/.prettierignore index 5dc073f..692aa34 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 284e842..70175ce 100644 --- a/.prettierrc +++ b/.prettierrc @@ -4,5 +4,4 @@ "singleQuote": false, "tabWidth": 2, "trailingComma": "es5" -} - +} \ No newline at end of file diff --git a/404.html b/404.html index 1e7a37e..5fde966 100644 --- a/404.html +++ b/404.html @@ -1,6 +1,6 @@ --- layout: default -title: Page not found +title: 404 permalink: /404 nav_exclude: true search_exclude: true diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..5f0ddae --- /dev/null +++ b/Dockerfile @@ -0,0 +1,13 @@ +FROM ruby:2.6 + +ENV LC_ALL C.UTF-8 +ENV LANG en_US.UTF-8 +ENV LANGUAGE en_US.UTF-8 + +WORKDIR /usr/src/app + +COPY Gemfile just-the-docs.gemspec ./ +RUN gem install bundler && bundle install + +EXPOSE 4000 + diff --git a/README.md b/README.md index 90dfb6f..019a741 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@

- Gem version Build status + Gem version Build status



Just the Docs

A modern, highly customizable, and responsive Jekyll theme for documentation with built-in search.
Easily hosted on GitHub Pages with few dependencies.

-

See it in action!

+

See it in action!




@@ -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 @@ -33,17 +44,21 @@ Or install it yourself as: $ gem install just-the-docs +Alternatively, you can run it inside Docker while developing your site + + $ docker-compose up + ## 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 20bf8a1..dbe742f 100644 --- a/_config.yml +++ b/_config.yml @@ -16,10 +16,18 @@ 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"] +exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json", "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile" +, "docs/tests/" +] + +# Regression tests +# By default, the pages in /docs/tests are excluded when the ste is built. +# To include them, comment-out the relevant line above. +# Uncommenting the following line doesn't work - see https://github.com/jekyll/jekyll/issues/4791 +# include: ["docs/tests/"] # Set a path/url to a logo that will be displayed instead of the title #logo: "/assets/images/just-the-docs.png" @@ -33,13 +41,13 @@ search: heading_level: 2 # Maximum amount of previews per search result # Default: 3 - previews: 3 + previews: 2 # Maximum amount of words to display before a matched word in the preview # Default: 5 - preview_words_before: 5 + preview_words_before: 3 # Maximum amount of words to display after a matched word in the preview # Default: 10 - preview_words_after: 10 + preview_words_after: 3 # Set the search token separator # Default: /[\s\-/]+/ # Example: enable support for hyphenated search words @@ -57,14 +65,14 @@ 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 # Sort order for navigation links -nav_sort: case_insensitive # default, equivalent to nil -# nav_sort: case_sensitive # Capital letters sorted before lowercase +# nav_sort: case_insensitive # default, equivalent to nil +nav_sort: case_sensitive # Capital letters sorted before lowercase # Footer content # appears at the bottom of every page's main content @@ -73,7 +81,7 @@ nav_sort: case_insensitive # default, equivalent to nil back_to_top: true back_to_top_text: "Back to top" -footer_content: "Copyright © 2017-2020 Patrick Marsceill. Distributed by an MIT license." +footer_content: "Copyright © 2017-2020 Patrick Marsceill. Distributed by an MIT license." # Footer last edited timestamp last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter @@ -84,8 +92,9 @@ 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 # Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define @@ -99,6 +108,11 @@ ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (t plugins: - jekyll-seo-tag +kramdown: + syntax_highlighter_opts: + block: + line_numbers: false + compress_html: clippings: all comments: all @@ -106,3 +120,5 @@ compress_html: startings: [] blanklines: false profile: false + # ignore: + # envs: all diff --git a/_includes/fix_linenos.html b/_includes/fix_linenos.html new file mode 100644 index 0000000..6243fb0 --- /dev/null +++ b/_includes/fix_linenos.html @@ -0,0 +1,65 @@ +{%- comment -%} +This file can be used to fix the HTML produced by Jekyll for highlighted +code with line numbers. + +It works with `{% highlight some_language linenos %}...{% endhighlight %}` +and with the Kramdown option to add line numbers to fenced code. + +The implementation was derived from the workaround provided by +Dmitry Hrabrov (DeXP) at +https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901 + +EXPLANATION + +The HTML produced by Rouge highlighting with lie numbers is of the form +`code table`. Jekyll (<= 4.1.1) always wraps the highlighted HTML +with `pre`. This wrapping is not only unnecessary, but also transforms +the conforming HTML produced by Rouge to non-conforming HTML, which +results in HTML validation error reports. + +The fix removes the outer `pre` tags whenever they contain the pattern +``. + +Apart from avoiding HTML validation errors, the fix allows the use of +the [Jekyll layout for compressing HTML](http://jch.penibelst.de), +which relies on `pre` tags not being nested, according to +https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-172069842 + +USAGE + +(Any names can be used for `some_var` and `some_language`.) + +{% capture some_var %} +{% highlight some_language linenos %} +Some code +{% endhighlight %} +{% endcapture %} +{% include fix_linenos.html code=some_var %} + +For code fences: + +{% capture some_var %} +```some_language +Some code +``` +{% endcapture %} +{% assign some_var = some_var | markdownify %} +{% include fix_linenos.html code=some_var %} + +CAVEATS + +The above does not work when `Some code` happens to contain the matched string +`
`. + +The use of this file overwrites the variable `fix_linenos_code` with `nil`. + +{%- endcomment -%} + +{% assign fix_linenos_code = include.code %} +{% if fix_linenos_code contains '
' %} + {% assign fix_linenos_code = fix_linenos_code | replace: '
', '
' %}
+  {% assign fix_linenos_code = fix_linenos_code | replace: "
", "" %}
+{% endif %}
+{{ fix_linenos_code }}
+{% assign fix_linenos_code = nil %}
diff --git a/_includes/footer_custom.html b/_includes/footer_custom.html
new file mode 100644
index 0000000..64e08c2
--- /dev/null
+++ b/_includes/footer_custom.html
@@ -0,0 +1,3 @@
+{%- if site.footer_content -%}
+  
{{ site.footer_content }}

+{%- endif -%}
diff --git a/_includes/head.html b/_includes/head.html
index 4f22497..c0f73d7 100644
--- a/_includes/head.html
+++ b/_includes/head.html
@@ -10,9 +10,9 @@
     {% endif %}
   {% endunless %}
 
-  
+  
 
-  
+  
 
   {% if site.ga_tracking != nil %}
     
@@ -27,9 +27,9 @@
   {% endif %}
 
   {% if site.search_enabled != false %}
-    
+    
   {% endif %}
-  
+  
 
   
 
diff --git a/_includes/header_custom.html b/_includes/header_custom.html
new file mode 100644
index 0000000..e69de29
diff --git a/_includes/nav.html b/_includes/nav.html
index f2ec7e5..325a68c 100644
--- a/_includes/nav.html
+++ b/_includes/nav.html
@@ -1,55 +1,99 @@
 
diff --git a/_includes/vendor/anchor_headings.html b/_includes/vendor/anchor_headings.html
index 985f448..e9ca862 100755
--- a/_includes/vendor/anchor_headings.html
+++ b/_includes/vendor/anchor_headings.html
@@ -1,18 +1,44 @@
 {% capture headingsWorkspace %}
   {% comment %}
-    Version 1.0.3
+    Copyright (c) 2018 Vladimir "allejo" Jimenez
+
+    Permission is hereby granted, free of charge, to any person
+    obtaining a copy of this software and associated documentation
+    files (the "Software"), to deal in the Software without
+    restriction, including without limitation the rights to use,
+    copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following
+    conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+    OTHER DEALINGS IN THE SOFTWARE.
+  {% endcomment %}
+  {% comment %}
+    Version 1.0.7
       https://github.com/allejo/jekyll-anchor-headings
 
     "Be the pull request you wish to see in the world." ~Ben Balter
 
     Usage:
-      {% include anchor_headings.html html=content %}
+      {% include anchor_headings.html html=content anchorBody="#" %}
 
     Parameters:
       * html          (string) - the HTML of compiled markdown generated by kramdown in Jekyll
 
     Optional Parameters:
       * beforeHeading (bool)   : false  - Set to true if the anchor should be placed _before_ the heading's content
+      * anchorAttrs   (string) :  ''    - Any custom HTML attributes that will be added to the `` tag; you may NOT use `href`, `class` or `title`;
+                                          the `%heading%` and `%html_id%` placeholders are available
       * anchorBody    (string) :  ''    - The content that will be placed inside the anchor; the `%heading%` placeholder is available
       * anchorClass   (string) :  ''    - The class(es) that will be used for each anchor. Separate multiple classes with a space
       * anchorTitle   (string) :  ''    - The `title` attribute that will be used for anchors
@@ -42,17 +68,22 @@
     {% assign nextChar = node | replace: '"', '' | strip | slice: 0, 1 %}
     {% assign headerLevel = nextChar | times: 1 %}
 
-    
+    
     {% if headerLevel == 0 %}
-      {% if nextChar != '<' and nextChar != '' %}
+      
+      {% assign firstChunk = node | split: '>' | first %}
+
+      
+      {% unless firstChunk contains '<' %}
         {% capture node %}{% endcapture %}
+    {% assign _workspace = node | split: _closingTag %}
     {% assign _idWorkspace = _workspace[0] | split: 'id="' %}
     {% assign _idWorkspace = _idWorkspace[1] | split: '"' %}
     {% assign html_id = _idWorkspace[0] %}
@@ -64,7 +95,7 @@
     {% capture anchor %}{% endcapture %}
 
     {% if html_id and headerLevel >= minHeader and headerLevel <= maxHeader %}
-      {% capture anchor %}href="#{{ html_id}}" aria-labelledby="{{ html_id}}"{% endcapture %}
+      {% capture anchor %}href="#{{ html_id }}"{% endcapture %}
 
       {% if include.anchorClass %}
         {% capture anchor %}{{ anchor }} class="{{ include.anchorClass }}"{% endcapture %}
@@ -74,6 +105,10 @@
         {% capture anchor %}{{ anchor }} title="{{ include.anchorTitle | replace: '%heading%', header }}"{% endcapture %}
       {% endif %}
 
+      {% if include.anchorAttrs %}
+        {% capture anchor %}{{ anchor }} {{ include.anchorAttrs | replace: '%heading%', header | replace: '%html_id%', html_id }}{% endcapture %}
+      {% endif %}
+
       {% capture anchor %}{{ include.anchorBody | replace: '%heading%', header | default: '' }}{% endcapture %}
 
       
@@ -93,8 +128,17 @@
           {{ header }}{{ anchor }}
         {% endif %}
         {{ include.bodySuffix }}
-      
     {% endcapture %}
+
+    
+    {% assign chunkCount = _workspace | size %}
+    {% if chunkCount > 1 %}
+      {% capture new_heading %}{{ new_heading }}{{ _workspace | last }}{% endcapture %}
+    {% endif %}
+
     {% capture edited_headings %}{{ edited_headings }}{{ new_heading }}{% endcapture %}
   {% endfor %}
 {% endcapture %}{% assign headingsWorkspace = '' %}{{ edited_headings | strip }}
diff --git a/_layouts/default.html b/_layouts/default.html
index 1d41a71..40d85ac 100644
--- a/_layouts/default.html
+++ b/_layouts/default.html
@@ -48,10 +48,25 @@ layout: table_wrappers
       
     
     
     

-      This site uses Just the Docs, a documentation theme for Jekyll.
+      This site uses Just the Docs, a documentation theme for Jekyll.
     

   
   

@@ -65,6 +80,7 @@ layout: table_wrappers
           

         

       {% endif %}
+      {% include header_custom.html %}
       {% if site.aux_links %}