Ki’Tok v 2.0


A WordPress Theme by Sujay Sarma


Introduction

Ki’Tok was born out of frustration. The cliched phrase: “Necessity is the mother of invention”. I didn’t know much PHP. I could read PHP-code, figure out what it was for and make really small changes to it to adjust it to do what I wanted. But not nearly enough to roll out my own theme.

A couple of years ago, I tried my hand at running an independent tech magazine, Manogata, online. WordPress was the perfect CMS system for this as it had everything I wanted, out of the box. The problem was presenting the public-facing user experience. I scrounged around for good themes and found “none” that fit my needs at an affordable price-point [free, essentially, because I was trying to run this on a shoe-string budget]. I ended writing my own theme, and am not ashamed to say this — thanks heavily to the Google search engine, documentation on WordPress Codex, a few answers on forums, and a lot in part to the source code of the themes bundled with WordPress.

For multiple reasons, Manogata never really took off. I found it tedious to have to come up with enough fresh content to retain any size of an audience. For more than a year, that code and the knowledge I had collected lay forgotten in a GitHub repo. Then, in the beginning of August, I needed to revamp my website (sujayvsarma.com) and include support for hosting YouTube videos and my (then in planning) Podcasts, as well as present the UX for my short stories and novels. I needed a single theme to do all of that, seamlessly. And I wanted to avoid “plugin-hell” altogether.

That is how Ki’Tok was resuscitated into this much more powerful avatar. I retained the name of the theme, because it has a rare, powerful meaning.

“That which has lived once, and shall live again, for ever.”

Ki’Tok” from “The Language of the Orions

Getting Ki’Tok 2.0

Ki’Tok is not and will never be available on WordPress Themes repository. The only way for you to get it is to use the instructions below.

Download the latest version (.zip file)

Only stable versions of Ki’Tok make it to this list. Previous versions can be found in this list, if for any reason you want to use them:

  • There are no older versions at this time.

Pre-requisites

Please ensure that you have these pre-requisites set up BEFORE you install Ki’Tok. It will save us some time and effort when things go wrong.

  • PHP: version 7.4+
  • WordPress: version 5.4+

I already know that Ki’Tok works well under the following, because I run it there myself:

  • Windows 10 with WSL2 + with Ubuntu, PHP 7.4, WordPress 5.5
  • WordPress on Azure (as an App Service with “MySQL InApp”) — this is how my website sujayvsarma.com runs!

Ki’Tok is also compatible with the following plugins that I use:

  • Akismet Anti-Spam (manages comment-spam)
  • FitVids for WordPress (provides resizing on my “YouTube Videos” pages)
  • WP Mail SMTP (powers email for my Contact form)
  • WPForms Lite (powers my Contact form)

Therefore you can safely use it if you have these plugins installed. If you notice any issues, do bring it to my attention because it would help me too!


Installing

WARNING! Please ensure that before you get cracking with Ki’Tok’s options and using the theme, you MUST configure your WordPress. This means you go into your Settings and your Appearance menus in /wp-admin and set up everything first. Only after you have finished all that, you should start with Ki’Tok. There are no specific settings, but you need to get them first, otherwise Ki’Tok may use its own settings that will cause you anxiety.

If you want to install it into WordPress:

  1. Go into the WordPress /wp-admin > Appearance > Themes.
  2. Click the “Add New” button.
  3. Once on the page, you will see the “Upload Theme” button. Click that, you will see a means to upload a .zip file.
  4. Click “Choose File” and then “Install Now”.
  5. Wait patiently. Depending on your Internet and your WordPress system’s speeds, it may take from a few seconds to a couple of minutes.

If you want to do a file-copy:

  1. Use your favourite unzip program and unzip the contents into your WordPress directory’s “/wp-content/themes” sub-directory.
  2. The finished structure must look like “…/wp-content/themes/kitok2/” [you should see .php files and more subfolders etc here].

Configuring Ki’Tok 2.0

Out of the box Ki’Tok configures itself with what I consider as “reasonable defaults”. They may not work for you. But no matter, Ki’Tok is designed to be incredibly powerful while remaining seamless. You choose your level of its poison. Here are some screens ( all of them on /wp-admin ) you should visit and satisfy yourself:

Appearance > Menus

One of the powerful features of Ki’Tok is its “automatic menu” system. But, if you have NO menus configured, it will not work. There will be no menus generated. This is by design, because the menus it generates depend on WHERE the menu is. The only way you tell WordPress (and hence Ki’Tok) where a menu is, is by creating one!

Create at least one menu. Here is how they will be used:

  • Top Horizontal Menu – will appear as a horizontal menu just under the site’s name and description. You can see it in action on my website just under my name: ( https://sujayvsarma.com ).
  • Bottom Footer Menu – will appear under the Copyright notice on the footer. Use this to designate your About / Legal and Social links.
  • Left Side Menu and Right Side Menu – are both designed to be menus that appear on the left and right sides of the UI. You can use this to place context or content sensitive menus.
  • Floating Menu – This is a menu that is always on the screen. Out of the box, it floats in a fixed position on the web page.

NOTE: At this time, only Top Horizontal Menu is used. The others will be built and released in future releases of Ki’Tok 2.0.

You must have at least one entry in the menu. If you want to use only the auto-menus, simply create a “Custom Link” entry called “Home” and set it to the “/” URL.

KiTok 2.0

This menu should appear on your WordPress Admin left-side menu bar somewhere under “Settings” depending on what other themes and plugins you have installed.

All options that you can configure for Ki’Tok can be found here.

HTML Generation Options

These options control how Ki’Tok generates certain HTML in the output. Each element has fairly descriptive help text right underneath the option. If you have questions, e-mail me and I will be glad to help you.

Post Types

This section lets you rename and play with the types of posts that Ki’Tok adds to your WordPress system. DO NOT change these settings unless you know what you are doing. The good news is that none of the options will change your existing posts under that type.

Each of the options under “Post Types” also mentions its default value. This is the value that is set in Ki’Tok when you installed it into WordPress. If you get into trouble, change the values back to the indicated defaults. Depending on the steps you took, you may need to run minor updates in the MySQL database for your site to fix some broken links.

NOTE about “URL Slug”

This setting actually changes the “Permalink” structure for your WordPress installation. If you change one of these options and hit the “Save theme options” button at the bottom, ti will cause an automatic reload of the Permalink structure. You do NOT need to go into the Settings > Permalinks page to do this yourself.


Resizing Videos

When you use the Embed feature of WordPress’s Gutenberg editor in the Add or Edit screens of Video posts, they will not resize correctly on the website. To fix this, I recommend using the “FitVids for WordPress” (by Kevin Dees) plugin.

If you are placing a YouTube Subscribe button widget on your website, you will notice it conflicts with FitVids and resizes to a strange size. To fix this, go into Appearance > FitVids and add the following to the “FitVids Ignore Selector” field:

div.#___ytsubscribe_0 > div.fluid-width-video-wrapper

Refresh the page where the subscribe button was and it should display correctly now.


Customizing Ki’Tok using code:

If you know enough PHP and want to root around the code and change things for yourself — or add additional post types you require or change how things are presented and so on, you may do so. There is no obligation for you to contribute your changes back to me.

HOWEVER, note that when I issue further releases of Ki’Tok 2.0 and you install them, you will need to use a code merge or DIFF tool to merge your customization into the new release code. THAT will be entire your problem. I cannot support YOUR changes or help you troubleshoot YOUR code.

Each function that is callable by custom code you can write is documented in-place using “bat-comment” comments. If you find functions that do not have these comments, DO NOT call them.

Documentation for arguments passed into functions [ if they are array-style arguments, then for each element of that array ], return values, defaults, etc are documented in-place in each function. Use your editor’s “Search across files” (usually SHIFT+CTRL+F, or use GREP) to find references to that function in my code and see how I use them.

I do NOT follow the wonky WordPress style of naming functions with “get_” or “the_” and so on to differentiate echo-ing and return-ing functions. The names of the functions tell me what they do, not the convention of naming. I do NOT intend to change this, that is MY coding style.

Please follow instructions in the Support section below to get further assistance in editing the code.


Support

The only place and way for support is to e-mail me. If you have my number, call me on the phone. I typically respond very quickly. Ensure that you have as much information as possible in your email or call, that way I can spend lesser time trying to figure out what went wrong.

The following information always helps:

  • What are you running WordPress on?
    • Windows or Linux? Which version?
  • Which version of WordPress do you have?
  • Which version of PHP do you have?
  • What plugins do you have installed?
  • Is this running on your local machine? If not, where (eg: hosting provider, Azure, Amazon…)?
  • What exact steps did you do when things became unexpected?
    • What did you expect?
    • What happened?
  • Did you try anything to resolve the problem on your own?
    • What have you tried and what happened?
  • Do you have your server’s ERROR log file(s) with you? If it was a code error, it will contain information to help me troubleshoot the issue.

End of this sweet and simple guide!