vsoch / docsy-jekyll

A Jekyll version of the beautiful Docsy!

Docsy Jekyll Theme

This is a starter template for a Docsy jekyll theme, based on the Beautiful Docsy that renders with Hugo. This version is intended for native deployment on GitHub pages. The original Apache License is included.

Changes

The site is intended for purely documentation, so while the front page banner is useful for business or similar, this author (@vsoch) preferred to have the main site page go directly to the Documentation view. Posts are still provided via a feed.

Usage

1. Get the code

You can clone the repository right to where you want to host the docs:

git clone https://github.com/vsoch/docsy-jekyll.git docs
cd docs

2. Customize

To edit configuration values, customize the _config.yml. To add pages, write them into the pages folder. You define urls based on the permalink attribute in your pages, and then add them to the navigation by adding to the content of _data/toc.myl. The top navigation is controlled by _data/navigation.yml

3. Options

Most of the configuration values in the _config.yml are self explanatory, and for more details, see the getting started page rendered on the site.

4. Serve

Depending on how you installed jekyll:

jekyll serve
# or
bundle exec jekyll serve

NOTE: If the above serve command throws an error saying require': cannot load such file -- webrick (LoadError) try to run bundle add webrick to automatically add the webrick gem to your Gemfile, or manually add gem "webrick" line to the Gemfile and then run the serve command again.

5. Run as a container in dev or prod

Software Dependencies

If you want to run docsy jekyll via a container for development (dev) or production (prod) you can use containers. This approach requires installing docker-ce and docker-compose.

Customization

Note that the docker-compose.yml file is using the jekyll/jekyll:3.8 image. If you want to make your build more reproducible, you can specify a particular version for jekyll (tag). Note that at the development time of writing this documentation, the latest was tag 4.0.0, and it had a bug that prevented the server from deploying.

If you are deploying a container to production, you should remove the line to mount the bundles directory to the host in the docker-compose.yml. Change:

    volumes: 
      - "./:/srv/jekyll"
      - "./vendor/bundle:/usr/local/bundle"
      # remove "./vendor/bundle:/usr/local/bundle" volume when deploying in production

to:

    volumes: 
      - "./:/srv/jekyll"

This additional volume is optimal for development so you can cache the bundle dependencies, but should be removed for production.

Start Container

Once your docker-compose to download the base container and bring up the server:

docker-compose up -d

You can then open your browser to http://localhost:4000 to see the server running.

Node : changes baseurl: "" in _config.yml when you are running in local and prod according to the requirement.

docsy-jekyll's Issues

Deletes the archive pages from the Document's quick jump.

Document pages will automatically render all pages in site.docs through Jekyll, which also contains pages under Archive. This causes a lot of duplication of these quick jumps, especially if there are more versions. I recommend filtering this out with an if statement.
Like this:

<!-- /pages/docs.md -->
<div class="section-index">
    <hr class="panel-line">
    {% for post in site.docs  %}
    {% assign path_segment = post.url | split: "/" | slice: 2 %}
    {% if path_segment != "Archive" %}
    <div class="entry">
    <h5><a href="{{ post.url | prepend: site.baseurl }}">{{ post.title }}</a></h5>
    <p>{{ post.description }}</p>
    </div>
    {% endif %}
    {% endfor %}
</div>

Multiple levels of children in _toc.yml?

Hi,

Does _toc.yml support nested children:? e.g.

- title: Documentation
  url: '#'
  links:
    - title: Overview
      url: '#'
    - title: Installation
      url: installation
      children:
        - title: Type
          url: installation/type
          children:
          - title: Water
            url: installation/type/water
          - title: Sand
            url: installation/type/sand
          - title: Fire
            url: installation/type/fire
        - title: Organization
          url: installation/organization
    - title: Architecture
      url: architecture

Need some help with Jekyll; no idea how to reach you

Dr. Sochat, I wanted to ask you a question about Jekyll, but I can't locate an email address for you. You seem to have solved the problem of the trailing JSON comma quite elegantly, but I'm having trouble applying your solution to my problem.

Would you be willing to tell me what I'm doing wrong here? I would be much obliged, because I don't want to insert any empty JSON elements either...

Here is the source of my woe, search.json:

[
{% for page in site.html_pages %}
{% unless page.search == "exclude" %}
{
"title": "{{ page.title | escape }}",
"tags": "{{ page.tags }}",
"keywords": "{{page.keywords}}",
"url": "{{ page.url | remove: "/"}}",
"summary": "{{page.summary | strip }}"
}
{% unless forloop.last and site.posts.size < 1 %},{% endunless %}
{% endunless %}
{% endfor %}

{% for post in site.posts %}

{
"title": "{{ post.title | escape }}",
"tags": "{{ post.tags }}",
"keywords": "{{post.keywords}}",
"url": "{{ post.url | remove: "/" }}",
"summary": "{{post.summary | strip }}"
}
{% unless forloop.last %},{% endunless %}
{% endfor %}

]

Thank you in advance for any help!

Issue: about.md has repo/user instead of user/repo for link generation

The about.md file uses {repo}/{user} instead of {user}/{repo}.

Subfolder does not display content, but shows 404 when viewed from nested page

I am having trouble viewing subfolders after I have drilled down to content.
For example, when I am viewing there is the pseudo-path above it, [Documentation / Subfolder / A Nested Page]. If I want to open the subfolder I get a 404 error and not the content of the subfolder as I would expect.
I would like to have my folder open with the contents showing, similar to the document page that shows the md files. Originally I added an 'index.md' file into each folder with a re-direct sending the viewer back to the home/index page. This did not work.
Is there something I am missing or is this an issue?
Thank you
M

How to change text formatting

Greetings V,
I am trying to change the text formatting after code snippets are shown. I am using Python and would like to show the code result just below it. I know some put '#' hashes in front of the result in the code block but I would like to show RIGHT below. Where is the CSS for that aspect? Can you help?

TY

Top level link missing in breadcrumb

Breadcrumbs are missing the top level link. Currently it just links to the same page which doesn't helpful for the user.

Expected behaviour:
Documentation > Get Started
I.e.: https://example.docsy.dev/docs/getting-started/

Actual behaviour:
Get Started
I.e.: https://vsoch.github.io/docsy-jekyll/docs/getting-started

~~Windows can't use docsy-jekyll~~ jquery can't be loaded in China

Hi,
Thanks for docsy-jekyll.
I run it on Windows Subsystem Linux, and it works. However when I open the website by chrome, the response is too slow to bare. At the same time, toc in the right sidebar doesn't appear. When I run it on Linux, everything is ok. So I thought it may be caused by WSL.
Interesting thing happens: I deploy it to github pages, then the same problem arises when visiting using Windows chrome(slow & no toc in the right sidebar). At the same time, vising using Linux chrome is totally ok.
Any idea what happens?
Thanks in advance.

Add support for webrick dependency or update readme.md to add guiding steps

Problem Statement : bundle exec jekyll serve fails on Ruby 3+.

Error thrown :

require': cannot load such file -- webrick (LoadError)

Expected :
bundle exec jekyll serve should work fine and serve the site.

Current workaround :

1. Execute bundle add webrick and then run bundle exec jekyll serve
2. Add gem "webrick" to the gemfile and run bundle exec jekyll serve

Possible solutions:

• 1. Update the Gemfile with gem "webrick"
• 2. Update the readme.md to highlight above two workarounds.

First Solution makes more sense to me as users of this project won't have to deal with the dependency themselves anymore, but it shouldn't hurt to update the readme.md file too along with it.

If this makes sense to all, I'll gladly raise the PR for Gemfile and ReadMe changes.

Similar discussion can be found here : jekyll/jekyll#8523

CSS and javascript not loading

Hi!
I followed the tutorial under the usage section on the readme file but my website only displays the HTML, no CSS or JavaScript.
Please, take a look: https://uaibot.github.io/

How can I reference the content of another data file within a data file?

How can I reference the content of another data file within a data file

Question: Multiple first-level entries in sidebar?

Hi,
I was trying to add multiple first level entries in the sidebar. This should be possible by modyfying the toc.yml file but resulted in nested unordered lists. As far as I can see there are some and closing tags missing in the sidebar.html file.

Reorganize the Getting Started page to reflect workflow

Hi vsoch,
I have several potential documentation issues that could be worked on and then tackled in small, simple steps. I want to outline several steps that I could work on with your approval.

1. May I suggest changing the outline of the Getting Started page.
2. (H1)Getting Started
3. Add color to docsy-jekyll.png to highlight areas of interest.
4. (H2)Prerequisites (change name from Development)
5. (H3)Installing on OSX directions
6. (H3)Install on Ubuntu procedure
7. (H2)Install code base
8. (H3) git on local harddisk
9. (H3) or via GitHub starter template
10. (H3) How to run jekyll server
11. (H2) Changing config.yml
12. (H3) Describe general steps
13. Add Instructions to change _config.yml in .yml document
14. Add additional note to _config.yml line 26 for clarity
    ...

With your guidance, I could work on these steps in order (one by one) or we could discuss broader changes.

I look forward to working on this with you,
MCC

Is there a way to make links collapsible in the sidebar?

Is there a way to edit the sidebar.html file in order to make the sections of the toc.yml (like "Documentation" or "Extras" in the example site: https://vsoch.github.io/docsy-jekyll/) collapsible just like in the Pandas API Reference (https://pandas.pydata.org/docs/reference/index.html)? In the Pandas documentation, only when you click the name of a section (like Input/output, General functions, etc...) do the pages related to that section appear. Is there a way to easily implement this behavior using the Docsy Jekyll Theme?

Issue: Changing assets in assets/favicons/ doesn't change icon on homepage

Icons are changed inside assets/favicons/

website doesn't change

built fine and it is loading as the favicon the browser is loading has changed

Guidelines for using docsy-jekyll in an enterprise project

I see that this project is licensed under Apache v2 which mean it is free to use/modify.
On the surface of it this license looks so simple. But once you read through it it tries to complicate things a bit like.
How should one use this theme for company's internal projects ?
What all things should one keep in mind what modifications can be done ?
The Apache v2 demands that the license be carried forward to the downstream derivate work. Does this carry forward of license bring in the insecurity/fear of exposure of work as far as usage in an Enterprise setup is concerned(as the derivative work is also containing Apache v2 license) ?

I believe Licensing is a topic that cannot be understood by just reading through it. Let's agree License/Notices are not easy to understand.

Question: what does the "integrity" variable in _includes/head.html do?

integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8="

test

Question on: https://github.com/vsoch/docsy-jekyll/tree/master/pages/index.md

Subfolder not viewable via 'A Nested Page'

Hi Vsoch,
I have a question about viewing the 'Subfolder` that is nested in your Docs. When I go to the 'A Nested Page' I am unable to go up one level to the subfolder by using the breadcrumbs. If you navigate to the link below and try the breadcrumbs you will find a 404.
https://vsoch.github.io/docsy-jekyll/docs/subfolder/example-page

I would like to set my docsy site to be able to see the nested folders. I I would like to view the 'chapters'... Is that possible?
https://mccurcio.github.io/docs/chapters/logistic-regression-for-binary-classification
Was Docsy-J written with this in mind? or no?
Any advice you have would be appreciated.
TY

Copyright, attribution, etc questions for my fork

Hi @vsoch , I am posting here to let you know that I have forked this awesome theme and am maintaining an unsynced repo. I have maintained heavy attribution and all your copyright notices and so forth, but that this point I think there is little left of your original code, and most of it is in the general layouts and templates. I expected to hue much closer to what you had, because I really liked it, but at this point I'm more concerned that your name is all over something that maybe doesn't look much like your work.

I'm fine with carrying all that attribution forward, but I'd slightly prefer to reduce it to a mention somewhere. For instance, I'm happy to credit/link to you in the first paragraph of the Readme in perpetuity. So if you have a chance to look and you'd rather have your name removed from files and the copyright file, or whatever you prefer, please let me know here. (I could issue a PR to this repo if that will help you compare, or you can do it on your end.)

https://github.com/DocOps/asciidocsy-jekyll-theme

Thanks!

Is tags page required in the local repo from the remote theme?

If we want to make changes to the tags page in a remote theme like https://github.com/vsoch/docsy-jekyll/blob/master/pages/tags.html, can those changes through the remote theme, without including the pages in the repository that uses the template?

Notice we have removed the tags and search pages from our repo https://github.com/microsoft/PartnerResources and this results in a 404:

Things to do:

• customize alerts
• customize badges
• ensure that quotes are appropriately styled
• add descriptions to all links, render in main page
• add stars display / repo to top right akin to mkdocs-jekyll
• search shouldn't be Google Search (lunr.js?)

White Header Menu with black text

I see the default header is a blue color.

When I set the color in _config.yml to color: "#FFFFFF" my header becomes this hiding most of the text unless I highlight to reveal it has also been set to white.

[Feature request] Tag support

Feature idea

Adding tags (keywords) in frontmatter (meta-data) will generate a page referencing all pages containing this page.

Example:

In frontmatter you add (in YAML for example):

---
title: My Document
summary: A brief description of my document.
authors:
    - Waylan Limberg
    - Tom Christie
date: 2018-07-10
some_url: https://example.com*
tags:
    - dev
    - python
---

So it will create a endpoint http://example.org/tag/#dev and http://example.org/tag/#python referencing, respectively, all pages containing the dev tag and the python tag.

Then on the page of the documentation where there is such a tags frontmatter, the page will contain some tag link #dev and #python respectively referencing the previously mentioned endpoints.

Related

The feature already exists in Jekyll, there is just to use it in the theme :)

A more heated discussion on why it is useful to have tags on documentation : mkdocs/mkdocs#1828

Similar issue in Jekyll documentation themes:

• just-the-docs/just-the-docs#255

Example

This feature is already introduced in Documentation Next Jekyll theme.

See https://idratherbewriting.com/documentation-theme-jekyll-next-version/sample1.html

Indented sub titles

Wouldn't it be better if "User Interaction" and "Search" were indented under "Features" the same way "Features" is under "Getting Started"?

Question: Tags are not working ?

Question on: https://github.com/vsoch/docsy-jekyll/tree/master/_docs/getting-started.md

Hey Vanessa,

is there a way to make the tags visible to these pages.

Thanks,
Anup

Question: Does this theme support versioning?

Understanding that software moves through versions over time, does this theme support having different versions of the docs?

Sidebar inner link are visible always

The inner(child) links inside the sidebar(left one) are always visible.

They would be ideally hidden if the parent is not selected
ie
https://example.docsy.dev/docs/tasks/
It only shows the inner link under the selected page and hide the rest

E.g.
https://example.docsy.dev/docs/concepts/
Here all the others are hidden since no child page is linked

So the expected behaviour is show child links only for the selected parent on the left sidebar.
Also in the original if the very top level is selected (documentation) it shows everything again.

Issue: _includes/google-analytics.html does not reference the _config.yml variable and is hardcoded, instead.

Line 6//
ga('create', 'UA-00000000-0', 'auto');

Issue with LICENSE.md

Problematic line:
Copyright [yyyy] [name of copyright owner]
Resolution:
Edit line to reflect owner's name and year of copyright

Add multi-layerd drop downs in navigation menu

Is it possible to create a navigation menu that's N layers deep? The example only shows a maximum of two drop downs items.
Like Documentation > Getting Started > Features.

I would like to create something like this

export page to PDF

How can I add export to PDF function tho the docsy theme ? I want to add visible button to every page/post so it can print it to the PDF automaticly. Is there some .js function or HTML ?

Point edit this page button to different branch?

Is this possible?
For example when I click that button it brings me to https://github.com/vsoch/docsy-jekyll/edit/master/_docs/getting-started.md, but I would like to point it to a different branch like https://github.com/vsoch/docsy-jekyll/edit/main/_docs/getting-started.md.

All the permalinks link back to https://vsoch.github.io/[permalink]

as title says. I use this for my site and i've done some digging and still can't find why it's doing this. already changed my info in in the _config.yml

404'd from Getting Started

If you click on this link:

Help-First Template Trial Problem

Dear Vanessa,
I am having problems with the first use of your docsy template. I have tried to use your template two ways.

1. by using "Use the template" button
2. by downloading the zip file
   Both times the mccurcio.github.io displays the svg icon on the front page out of proportion with the HTML.
   I have tried changing the config.yml to fit my situation. It builds nicely and looks fine when I use my computer, etc. I am not sure where to look next.
   This time I did nothing to limit the number of problems I introduced.
   Any suggestions?
   I know you must be busy but I have tried beating my puny head and it really hurts. ;D
   TY,
   Matt

Repository name minimum width

The repository name (in the top right) needs to have a minimum width (150px) otherwise the second line of text wraps on itself (and it doesn't look great). I just learned this by testing a short repository name.

Creating a TOC for a page/links to sub headings

I am extracting a wiki that I have been maintaining in mediawiki to create a GitHub-hosted site. I really like your docsy template! One thing that I like about mediawiki is that if a page has enough headers it creates a TOC for that page to speed up navigation. With this it also creates links to those headers. Is anything like this possible with the current version of the template or is something in the works?

Search not working

Hello! Thank you so much for your work on docsy-jekyll. It is wonderful and versioning is a killer feature! I am new to Jekyll and have run into a small problem getting the template project up and running.

I cloned the repo and have Jekyll running locally. The docsy-jekyll template looks great, however, search is not working. Entering a term to search does nothing.

I am running Chrome on Windows 10. When I run the site with Chrome in developer tools mode I see the following error:

Failed to find a valid digest in the 'integrity' attribute for resource 'http://127.0.0.1:4000/docsy-jekyll/assets/js/jquery-3.3.1/jquery-3.3.1.min.js' with computed SHA-256 integrity 'T+aPohYXbm0fRYDpJLr+zJ9RmYTswGsahAoIsNiMld4='. The resource has been blocked.

How can I fix this? Thanks!

Search results show "news" posts incorrectly

e.g. if you search for "welcome" one of the search results (the one referring to the "Welcome to MkDocs Jekyll" news post) will have no title or clickable link, with html markup visible in the following text.

This is true for all news posts.