KDoc - a new Kirby theme for documentation sites

Plugins
1

I’m pretty excited about my first Kirby “theme” offering. It’s free to use, and I think potentially useful for documentation sites of all kinds. It’s a basic theme by design, but clean and read-able too.

I’ve included @bastianallgeier’s statify script, so that you can host your site on Github Pages if you like.

This is both a demo of the theme, as well as information about it:
http://nsteiner.github.io/kdoc/

Suggestions, question, and feedback are greatly appreciated.
Cheers - Nate

4 Likes
2

In terminal run npm install to get a small local build setup, this requires Node.js. You only need to do this the first time. Run npm run dev which should open up your default browser with the site running!

Is Node.js a requirement for this theme? That seems like a lot of overhead.

I just cloned this to my computer’s local Apache/PHP environment and I’m getting 404 errors on all pages except the home page.

3

I’m using Node only to process SCSS and to serve it locally via PHP. It shouldn’t be required, but I haven’t tested it. I’ll give it a shot and see.

4

Ok @samnabi thanks for the bug report. If you pull the code again it should be fixed. I had failed to include the .htaccess file, which isn’t strictly required in the Node environment. I just tested in MAMP and it seems to work good out of the box now. Thanks again.

5

Aha, wonderful! It works now.

It might be a good idea to update the How to get started page, to clarify that Node is only required for processing SCSS.

Personally, I prefer to let my code editor compile my SCSS on save so this shouldn’t be a problem.

The theme looks great! I’m sure it will be useful to lots of us.

6

@samnabi Ok great.
Totally agree about updating the getting started page, doing so now!
Thank you.

7

Updated install page now outlines two methods:
http://nsteiner.github.io/kdoc/how-to-get-started/
:+1:

8

@nate. thank you so much for this awesome template and project. It looks really good!

I have tested it locally, and have a few small feedback for you:

  • I downloaded jquery locally to avoid lag in download online from google… this is especially useful for slow connections or offline. Modified snippets/footer.php and put
    <?php echo js('assets/js/jquery-2.2.0.min.js') ?>
    where the jquery line is.
  • An offline copy can be made with statify script, however that will always create links base on $root value inside the script. For a truly offline (static) version I used wget:
    wget -p -E -r -k http://localhost/kdoc
    (or whatever your URL may be). This will make a mirror of your site, and modify all links to be local. You can now copy the site anywhere, run off a USB stick etc. Wget is free
  • to deal with scss, I found a tool call sassc (“sassy”) built on Libscss. I do not have a C++ compiler, so I found a binary build. I am on Windows, and don’t want to install Ruby just for that. If you have Perl, and don’t want to run unknown programs, there is a module for scss as well. You may wish to include that option as well in description…

So all in all, I now have a near perfect toolchain… scss, kirby to make pages and structure, and wget to make local copy.

Nice part: content and layout completely separated.

Hope someone else can benefit from these notes.

Edit: using a directory monitor, I can easily automate builds of scss and output by putting watches on kdoc structure.This is probably trivial, but just wanted to mention.

1 Like
9

To compile SASS, JS, CSS, images and do plenty of other tasks I really recommend using Gulp. It’s a desktop application that runs on NodeJS.

Everything is set up in a gulpfile.js så coders love it. No UI.

It’s like a modern better version of Grunt. It’s better because:

  • It’s faster
  • One plugin only do one task
  • Shorter syntax
  • Better readability

I’ve read about many people leaving Grunt for Gulp but never the other way around. I use Gulp, everyday.

1 Like
10

i already have tested it localy and its Rly Amazing! :slight_smile: Thanks For That

1 Like
11

@myicq this is helpful feedback, thank you for taking the time to share it. I’ll respond to each point.

  • Local jquery is certainly an option. I’ve understood the hosted version to have somewhat of an advantage of being frequently cached (many sites use it so many users already have the cached version). Perhaps it’s better to have it included for the reasons you mentioned though.
  • This wget option is super helpful to know about. I had tried using wget a while back, but never got exactly the right combo of option flags from amongst the zillions of options. I just tried -pErk and it worked great. Relative paths are a bit more flexible too.
  • This is a good point about SCSS processing. I’m certainly sharing only one of many options out there for processing, and NodeJS is a good bit of overhead for such a minor part of this, if on doesn’t already have it.

Thanks again for this helpful feedback. I’m going to update the website with these points, or variations on them, very soon.

12

@jenstornell I :heart: gulp and use it regularly. You’ll get no argument about gulp vs grunt from me, I skipped the whole grunt trend entirely because gulp just felt easier to understand.

I didn’t include gulp in KDoc initially because I could offer a lot of value with straight npm scripts - which are also super fast. Do you think folks would prefer to start off with a gulp config, maybe more helper functions like BrowserSync?

13

Thanks for your kind note @simondev!

1 Like
14

If you want to make it a little bit easier for people to compile the sass-files I suggest that you change to Gulp. I think more are familier with that syntax. As there are thousands of plugins for it you might speed up the workflow in the end.

I bet your npm scripts are super fast, but Gulp tasks are not slow. I think the difference might be so small that you don’t benefit from it by running your own thing. And it does not affect the speed of the theme, just the compilation.

About BrowserSync. It’s the only plugin I tested that did not work well for me. It was slow and buggy. Maybe it works better on a Mac. You can include it if you want but I would have left it out.

15

@jenstornell that sounds like a good idea, npm scripts are a little harder to parse and (arguably) less easily extensible.
I’m curious if anyone prefers the npm script version, if it’s worth maintaining somewhere.

16

Hello - I’ve updated this theme in two ways:

  1. Javascript updated so that jQuery is no longer used. Add it in if you like, or not, but there should be no conflicts if you need to run an older version.

  2. The KDoc documentation/demo site has been enhanced, in part with info from @myicq.

I’m still considering @jenstornell’s suggestion to switch from npm script to gulp, I’m a bit on the fence about it and would appreciate more opinions if anyone has a preference.

Got feedback, suggestions or bugs? Please log 'em in github https://github.com/nsteiner/kdoc

Cheers.

1 Like
17

Hi Nat,
thanks for your work on KDoc, which is really cool. I have spend already half a day on using it.

I have a question about it (and maybe the use of themes in general):
A “theme” seems to be the whole directory tree of the kirby webtree. That means a Theme is like a fork of the (general purpose) kirby. Correct?

The reason I am asking is:
Can you use two Themes on one installation? Or more speciffic: Can I use the general Kirby installation and your KDoc installation in a subdirectory? I need a very simple version of KDoc, no scss etc.

The purpose could be of more general interst as well: Have a Marketing website, with a subdirectory for documentation (of the companies products).

I tried myself by coppying and renaming your templates head, foot and sidebar. I got a bit further, but run into difficulties. Would that be the way forward?

18

Hi @mmeinesz that sounds like a great idea. We’ve been using KDoc in it’s own little Kirby install, but having a way to apply it within another site makes a lot of sense.
I’ll think about how to accomplish this, and add it to the issues list in github.

19

Well, if you don’t need a single panel to control everything, the easiest way would be to just use a separate Kirby installation either parallel to Kirby or as a subfolder, and run that on a subdomain. But then this is a completely separate installation.

You could also put the files of one theme into the installation of the other theme, but you might run into difficulties if the template or snippet names have conflicts. You would have to start renaming files. Also, there might be problems with conflicting stylesheets.

20

OK, understood. Right now I have KDoc running on a different subdomain. I don’t like that option too much, as we will have to maintain an other server. So, as time allows we might “merge” the two servers into one.
thanks for your help