tomjoht / documentation-theme-jekyll Goto Github PK

There is no option for google-analitics in _config.yml.
But there is google-analytics tag file.
Maybe google-analytics option should be added.

https://github.com/tomjohnson1492/documentation-theme-jekyll/blob/82e4157a86b9d6e41a672b3f26a6619dbb2b4034/css/customstyles.css#L164-L166 is invalid CSS code.
The code was introduced by f8b9602 and as I do not know what its intention was, I purposely did not simply create a pull request removing it.

Currently the theme only supports the generation of pdfs based on prince which is quite expensive.

A free alternative to prince is wkhtmltopdf and support for it would be really awesome.

I am getting the following warnings when running my site locally:

Liquid Warning: Liquid syntax error (line 9): Unexpected character { in "{{ "tag_" | append: {{tag}}" in /layouts/post.html
Liquid Warning: Liquid syntax error (line 9): Unexpected character { in "{{ "tag" | append: {{tag}}" in /layouts/post.html
Liquid Warning: Liquid syntax error (line 10): Unexpected character { in "{{ "tag" | append: {{tag}}" in pages/news/news.html

Everything "appears" to be working fine?

Is it possible to move a logo from the footer to the left side of the top navigation bar? I need to do that to keep the documentation pages in the same style as the organization's main site. Thanks.

In http://idratherbewriting.com/documentation-theme-jekyll/mydoc_tables.html

Looking at the generated HTML markup, the ending </td> tag is getting picked up as Markdown and rendered as </td>. That's breaking all tables all the way down the line. This might be a Jekyll issue rather than with the theme.

The quick and dirty workaround: move the ending </td> tag to a new line.

Another, more minor issue: cells with the markdown="1" attribute are rendered vertically centered, while other cells in the same row are rendered top-justified. That's probably a CSS issue. Keeping all cells consistent is the workaround there.

The link in the README.md links to github.com/tomjohnson1492/documentation-theme-jekyll/blob/gh-pages/idratherbewriting.com/documentation-theme-jekyll, which is incorrect and comes up with a 404.

Hey great project. I have been trying this out as a documentation site and it works well. One issue I have though is that I would like to load remote README.md files from other repos I have. This is possible with this and other plugins - https://github.com/Rolinh/jekyll-remote-markdown

So I create the _plugins directory, upload the remote_markdown.rb, and put a tag in one of my pages like this:

{% remote_markdown https://raw.githubusercontent.com/Rolinh/jekyll-remote-markdown/master/README.md %}

All that happens is it just keeps showing the old page and never renders a new page. Should this work? Is there another way to get this to work? Any help would be appreciated.

I'm referring to yml files such as _data/sidebars/mydoc_sidebar.yml.

It seems daunting to add entries to the yml files manually if you have a lot of content files.

I see a lot of sites using this approach (yml file) to build their sidebar navigation, so I was wondering if there's some standard/common workflow to creating that yml file automatically or semi-automatically based on say folder structures.

What is the recommended way to insert code blocks inside an alert? The one below isn't rendering it as a code block.

{% include note.html content="This is my note. <br/><br/>

~~~
def foo(x):
    return x+1
~~~

" %}

Hi,
Very many thanks for all your work on this excellent codebase. It is a great job.

A question/issue re YAML please.
On editing some of the sidebar YAML files in the _data/ folder, am getting a build error on github pages.
So to troubleshoot the YAML syntax was trying to use a YAML validator such as http://beautifytools.com/yaml-validator.php

However if I put this yaml from your working demo code;
https://github.com/tomjohnson1492/documentation-theme-jekyll/blob/gh-pages/_data/sidebars/home_sidebar.yml
into that tool, am getting an error.
"Error : Unable to parse.
Line : 6 - title: Products"

So am struggling to work from a basic yaml syntax that is known to be valid YAML

Am assuming this is not completely unknown to you/others?

many thanks in advance
Tony

So we have this mydoc in the path for everything on the site, but it's in so many places: the directory structure, file names, and configuration files.

Am I missing a quick and easy way to properly change this to reflect the correct subdirectory for my project?

Hello,

First of all, thanks for this great theme.

Is there a plan to separate the products from the other files of the theme?

The idea would be to have the content of a product's documentation in a separate Git repository so it could have its own lifecycle.
The actual build could be performed either by providing a way to import the main project (containing the theme's files) in a product's project or simply by defining the product's repository as a submodule of the main one.

To do so, not only the pages of a product should be in a subfolder (such as "pages/product1" currently) but all the other references especially the sidebar of the product.

Thanks in advance.

I install all those thing step by step.

When I try to build the theme, with bundle exec jekyll serve

it occurs

Jekyll 3.4.5 erro: incompatible encoding regexp match (GBK regexp with UTF-8 string)

My local PC base on Chinese language.

the horizontal rules in markdown seem to be a series of hyphen like the sreen shot below, instead of the "normal" appearance.

I believe that the description of how Automated Links works is incorrect.
From the links page:

1. To link to a topic, use reference-style Markdown links, with the referent using the file name (without the file extension).

However the code in _includes/links.html indicates that these links are based on the url field of the page. The url field is derived from the filename and path of the source file but most of the example documentation pages have a permalink specified which overrides the default style. Most permalinks are all the same as the filename, with the addition of the .html extension and / character.

Renaming a markdown file does not break automated links like we would expect it to if the filename if automated links were based on file names. Only changing or removing permalinks will break them.

<p>{% if page.summary %} {{ page.summary | strip_html | strip_newlines | truncate: 160 }} {% else %} {{ post.content | truncatewords: 50 | strip_html }} {% endif %}</p>

There might be a little bug in page.summary, which should be post.summary.

I'm following the instructions to install this on my Mac (using Option 2 for use with github pages), but I get the following error:

  Liquid Exception: cannot load such file -- rouge in pages/mydoc/mydoc_help_api.md
bundler: failed to load command: jekyll (/usr/local/bin/jekyll)
LoadError: cannot load such file -- rouge
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/tags/highlight.rb:102:in `require'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/tags/highlight.rb:102:in `render_rouge'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/tags/highlight.rb:53:in `render'
  /usr/local/lib/ruby/gems/2.3.0/gems/liquid-2.6.1/lib/liquid/block.rb:109:in `block in render_all'
  /usr/local/lib/ruby/gems/2.3.0/gems/liquid-2.6.1/lib/liquid/block.rb:96:in `each'
  /usr/local/lib/ruby/gems/2.3.0/gems/liquid-2.6.1/lib/liquid/block.rb:96:in `render_all'
  /usr/local/lib/ruby/gems/2.3.0/gems/liquid-2.6.1/lib/liquid/block.rb:82:in `render'
  /usr/local/lib/ruby/gems/2.3.0/gems/liquid-2.6.1/lib/liquid/template.rb:128:in `render'
  /usr/local/lib/ruby/gems/2.3.0/gems/liquid-2.6.1/lib/liquid/template.rb:138:in `render!'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/convertible.rb:106:in `render_liquid'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/convertible.rb:233:in `do_layout'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/page.rb:122:in `render'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/site.rb:269:in `block in render'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/site.rb:268:in `each'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/site.rb:268:in `render'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/site.rb:46:in `process'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/command.rb:28:in `process_site'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/commands/build.rb:55:in `build'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/commands/build.rb:33:in `process'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/lib/jekyll/commands/serve.rb:25:in `block (2 levels) in init_with_program'
  /usr/local/lib/ruby/gems/2.3.0/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `block in execute'
  /usr/local/lib/ruby/gems/2.3.0/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `each'
  /usr/local/lib/ruby/gems/2.3.0/gems/mercenary-0.3.6/lib/mercenary/command.rb:220:in `execute'
  /usr/local/lib/ruby/gems/2.3.0/gems/mercenary-0.3.6/lib/mercenary/program.rb:42:in `go'
  /usr/local/lib/ruby/gems/2.3.0/gems/mercenary-0.3.6/lib/mercenary.rb:19:in `program'
  /usr/local/lib/ruby/gems/2.3.0/gems/jekyll-2.4.0/bin/jekyll:18:in `<top (required)>'
  /usr/local/bin/jekyll:22:in `load'
  /usr/local/bin/jekyll:22:in `<top (required)>'

I tried "gem install rouge", "bundle update", etc. but nothing seemed to help. What should I do?

When a sidebar entry contains links to lots of pages, the list is truncated at the bottom of the screen, whereas it should scroll.

To replicate:

• open a page. I'm running Firefox 43 on OSX, but the same happens in Chrome and Safari.
• shrink your browser window's height. I'm using a window size of about 1400x700 px. It needs to be wide enough to prevent the mobile layout from kicking in, but also not tall enough to display the entire list of pages in the sidebar.
• click to expand Publishing in the sidebar. You should see only some of the entries in that menu.
• Try scrolling

It might be easier to reproduce if more entries are added to the sidebar. I've got about 50 articles in one category- that's where I'm seeing the problem.

in order to be valid, the sitemap needs the full url,
Add a variable with hostname as a prefix
hostname: https://mydoc.com

i have added two permalink like below:
http://qinkun1234.github.io/b/mydoc_laravel5_1_manual/
but when i add the third permalink:
https://github.com/qinkun1234/b/commit/724500643d47e71275d8a06c85acc792542bc694

http://qinkun1234.github.io/b/mydoc_jwt/
it catch 404 File not found.
can u help me find where is the problem?

When clicking the dropdown menu in the topnav section, the subitems defined in the topnav.yml do not appear.

This is a really cool theme, thank you.

Since this theme is documentation-centric, I think it would be great if you could use asciidoc in addition to markdown.

I've tried just adding the jekyll-asciidoc plugin, but I can't seem to get adoc files to process. Either I get an error like Error: undefined methodempty?' for false:FalseClass` without any indication of what the offending file is (for just a regular page), or I get a post that has the raw asciidoc wrapped in a div.

Also, I'm just using the head of the repo, can't seem to find any "released" artifacts for this.

I'm not planning on publishing on Github Pages, so I went with Option 1: Build the Theme (without the github-pages gem). After deleting the Gemfile and Gemfile.lock files from the theme's root directory, I ran jekyll serve and received these Liquid Warnings:

 Generating...
    Liquid Warning: Liquid syntax error (line 93): Expected dotdot but found pipe in "{{(site.pages | sort: 'title') }}" in pages/mydoc/mydoc_kb_layout.md
    Liquid Warning: Liquid syntax error (line 140): Expected dotdot but found pipe in "{{(site.pages | sort: 'title') }}" in pages/mydoc/mydoc_tags.md
                    done in 7.298 seconds.

The site generated without issue, but I wasn't comfortable with the warnings, so I did a little research and found that parentheses are not allowed within Liquid tags. I the offending lines had dot references to other liquid tags, so I searched around the project and removed the offending parentheses. After saving -> killing the old serve -> serving again in a new terminal, the warnings were gone.

mydoc.pdf is broken (contains 191 blank pages).

Heyho,
I want to try out this theme but the site is not rendered as expected/does not look like the demo page.

I cloned the repo, installed bundler and jekyll, used bundle update, jekyll build and jekyll serve.
Now when navigating to localhost:4000, I get errors that some files are missing. Any ideas what to do? Thanks in advance!

Configuration file: /home/artur/Repos/documentation-theme-jekyll/_config.yml
            Source: /home/artur/Repos/documentation-theme-jekyll
       Destination: /home/artur/Repos/documentation-theme-jekyll/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
   GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
                    done in 2.799 seconds.
 Auto-regeneration: enabled for '/home/artur/Repos/documentation-theme-jekyll'
    Server address: http://127.0.0.1:4000/documentation-theme-jekyll/
  Server running... press ctrl-c to stop.
[2018-01-26 16:14:01] ERROR `/' not found.
[2018-01-26 16:14:01] ERROR `/css/modern-business.css' not found.
[2018-01-26 16:14:01] ERROR `/css/syntax.css' not found.
[2018-01-26 16:14:01] ERROR `/css/customstyles.css' not found.
[2018-01-26 16:14:01] ERROR `/css/theme-blue.css' not found.
[2018-01-26 16:14:01] ERROR `/js/jquery.navgoco.min.js' not found.
[2018-01-26 16:14:01] ERROR `/css/boxshadowproperties.css' not found.
[2018-01-26 16:14:01] ERROR `/js/customscripts.js' not found.
[2018-01-26 16:14:01] ERROR `/js/toc.js' not found.
[2018-01-26 16:14:01] ERROR `/js/jekyll-search.js' not found.
[2018-01-26 16:14:01] ERROR `/images/company_logo.png' not found.
[2018-01-26 16:14:02] ERROR `/js/jquery.navgoco.min.js' not found.
[2018-01-26 16:14:02] ERROR `/js/toc.js' not found.
[2018-01-26 16:14:02] ERROR `/js/customscripts.js' not found.
[2018-01-26 16:14:02] ERROR `/js/jekyll-search.js' not found.
[2018-01-26 16:14:02] ERROR `/images/company_logo.png' not found.

Hi,

I want the generated htmls to be put in specific dirs under _site. It works well with permalink: dir/page.html

However, this break all links to js and css files since they are being looked for in the same dir, not in the root where they are.

Anything I'm doing wrong?

Is it possible to support this theme as a Gem-based Jekyll theme?

I had problems spinning the project up with the docker build instructions. It seems like one of the ruby packages requires a more recent version of ruby, I got the error activesupport-5.0.0.1 requires ruby version >= 2.2.2, which is incompatible with the current version, ruby 2.1.10p492.

I changed FROM ruby:2.3 to FROM ruby:2.3 and re-ran the two commands and it worked. I'm hesitant to suggest this as a PR because I don't really work with ruby/docker, so I'm not sure if it really makes sense to use that version of ruby.

Using Chrome(ver 51, windows) to browse the demo page: http://idratherbewriting.com/documentation-theme-jekyll/index.html

I got this error in Chrome console:

index.html:1076
Uncaught TypeError: $(...).annotator is not a function

Hi,
I really like to thank you to share such a great theme. It looks like the best fit for our next documentation project and we are taking into account to use it. One thing I have not found so far is the License you are sharing this project. Could you please add a license file?

Cheers
Johannes

I'd like to adapt the knowledge-base layout to show five cells/icons/panels instead of four. But when I just add another <div> element with class="col-md-3 col-sm-6", I end up with the first four nicely top-aligned, but the fifth one appears below the forth one.

Any advice?

If I narrow the window width, I get three rows, but the fifth item is in the 2nd column instead of the first. If I narrow the window some but not enough to push any of the items to a next row, the fa (font awesome) icons lose their centered-ness.

I'm working on a content architecture scheme where I (hope to):

• Retain the "Products" dropdown in the topnav.
• Set up each product's (and an "All Products") landing page to display a workflow (in the knowledge-base format).
• The sidebar will be product/version specific, with the workflow phases as the top-level entries in the sidebar, and applicable doc titles (for the given product or version) being the 2nd-level entries in the sidebar.

On each product/version landing page, each phase in the workflow will have a link to the applicable tags_ page.

The problem is, that same tags page will be used in a variety of circumstances (multiple landing pages from the Products dropdown, multiple landing pages from an additional "Versions" dropdown, etc.), and so the sidebar entries need to change based on the current product/version that's selected.

Is this all achievable? I started this question thinking that my only issue was needing to have a dynamically-selectable sidebar, but then realized that there are lots of things that I'm looking to have dynamically determined (if I'm not to go crazy defining tags and sidebars for all possible permutations of product/version). So I might need to rethink all this.

After all, Jekyll is a "static" site generator!

Tried various stackoverflow js snippets but failed so far. Maybe there's a ready to use solution?

It should appear in the footer at least based on what I've gleaned so far but it doesn't. Is it a bug or am I missing something?

Even the demo site is missing it.

It's unclear to me when I should create a .html file and when I should create a .md file, within the context of this theme.

Looking at the sample implementation (the documentation for this theme), for two of the "products", product1 and product2, there's a p*_landing_page.html file in the product's dir/folder, along with lots of .md files. For the "default" (home) mydoc product, its "main" page, which is the Home page for the entire site, is index.md, and all the files that are under the mydoc dir/folder are .md.

It doesn't seem to matter whether one creates a .html vs. .md file; both seem to be usable in *_sidebar.yml files.

So is it simply a matter of whether one wants to have html or markdown code in that page?

It resolves to:

https://github.com/tomjoht/documentation-theme-jekyll/blob/gh-pages/pages/mydoc/mydoc_shuffle.md

It is because _layouts/page.html always assumes that the file is in .md format, while the mydoc_shuffle.html is an exception:

Line 44:

{{page.url | remove: ".html" | append: ".md"}}

Each news article (i.e. sample posts, welcome to jekyll, test post from last year) does not link properly to its respective page when you clicked on the news title.

We're finally updating the expdocs project from your original theme (born many moons ago) to your latest theme.

I downloaded your latest commit to test it before I rolled it out the the rest of the team and ran into an issue where PDFs weren't being generated.

Here are my steps to reproduce:

Working/serving/building/generating locally on my MacBook Pro.

1. Downloaded the latest theme.
2. Made sure all of my prerequisites were up-to-date.
3. Ran jekyll serve to make sure that everything was running locally.
4. Ran the PDF shell script . pdf-mydoc.sh to make sure I could generate PDFs. No PDF was generated.
5. I noticed an error in my terminal: prince: error: no input documents to process
6. I checked the _site/pdfconfigs/princelist.txt file. It was there, but it was empty ... well ... it had 4 empty lines.
7. I navigated to http://127.0.0.1:4010/mydoc-pdf/tocpage/ and saw the Table of Contents h1, but the rest of the HTML page was blank.

This sent me on a two day odyssey where I tried everything I could think of to fix the issue, and I couldn't get anything to work. Before bothering any of the Developers, I decided to look at the commit history on the theme and I noticed a fair amount of work on the sidebar code committed on June 5th. I downloaded the June 3rd commit and was able to generate the PDFs without issue.

I took a look at your changes on June 5th and they are way over my head.

I will wait for a fix for the broken PDF generation process. In the mean time, I'm going to continue my work with the coded committed on June 3rd.

If the newest version of the theme isn't meant to be built locally, but instead is only meant to be built in a Docker Container or someplace else, please let me know and we can close this issue as Won't FIx (or somethign like that).

thanks

Generating the docs based on audiences. This seems to work for the sidebar and topnav. However, all pages regardless of the audience associated with them are still printed.

Hi Tom @tomjohnson1492

First of all, thanks for this wonderful theme.

I have some issue in starting the Jekyll server at my local machine. Here is the error that I am getting. Let me know if you have seen this message before. I am on Slackware 14.2 and followed the getting started instructions to upgrade the bundle..

bash-4.3$ bundle exec jekyll serve Configuration file: /home/ashutosh/documentation/_config.yml Configuration file: /home/ashutosh/documentation/_config.yml jekyll 3.3.1 | Error: Could not find a JavaScript runtime. See https://github.com/rails/execjs for a list of available runtimes.
After seeing this message, I installed the execjs too from above link. But it didn't work.

Thanks in advance

Is there a feature to auto-generate sidebars from page headings?

For example:

- page 1
    - page 1 heading 1
    - page 1 heading 2
    - page 1 heading 3
- page 2
    - page 2 heading 1
    - page 2 heading 2
    - page 2 heading 3

I looked through the docs but nothing jumped out at me.

The search wasn't working in my site, so I took your advice and looked in search.json for any invalid JSON. The only error was an extra comma after the entry for the last page, before the closing bracket. Like this:

[
{... lots of pages},

{
"title": "title",
"tags": "",
"keywords": "",
"url": "title.html",
"summary": ""
},
]

When I removed that last comma, the search started working properly.

I checked all the non-HTML pages that might be included, and they are all properly excluded from search.

Any ideas how or why that last comma is being inserted there? Or how to prevent it from being inserted?

bundle install did not install all gems.

on jekyll serve I got this error

WARN: Unresolved specs during Gem::Specification.reset:
jekyll-watch (~> 1.1)
WARN: Clearing out unresolved specs.
Please report a bug if this causes problems.
Configuration file: /Users/mike/Src/ThingStudio/documentation-theme-jekyll/_config.yml
Dependency Error: Yikes! It looks like you don't have kramdown or one of its dependencies installed. In order to use Jekyll as currently configured, you'll need to install this gem. The full error message from Ruby is: 'cannot load such file -- kramdown' If you run into trouble, you can find helpful resources at http://jekyllrb.com/help/!

I had to remove Gemfile.lock and re-run bundle install to get it to work.

This is related to jekyll/jekyll-help#298. I have inserted an include for the toc.html file in my default layout html file, but the toc isn't showing up. Looks like this may be a bit more complicated, with inclusion of some javascript for generating the toc?

This is what default.html looks like:

{% include head.html %}

    {% include nav.html %}

    <h1>{{ page.title }}</h1>

    <hr/>

    {% include toc.html %}

    <section id="main_content">

    <main role="main">
        {{ content }}
    </main>

{% include foot.html %}

In my head.html I'm including: <script src="{{ "/js/toc.js" | prepend:site.baseurl }}"></script>, and I placed toc.js in a js folder. I'm guessing that I'm missing something.

Thanks!

Running the site locally without any modifications (just downloaded the release zip and jekyll serve) launches the site but you're greeted with a page not found message on the landing page.

The demo site itself points to mydoc/home.html and if I navigate to localhost:4009/mydoc/home.html, I see the home page.

Navigating to just localhost:4009 produces that landing page which looks for home.html in the root directory (and is missing).

Hi Tom,
how can we generage a page wich links to the "last changed" pages? This would be VERY helpful.
Thanks in advance
Stefan

Your theme has been listed on https://jekyll-themes.com/.