huge readme refactoring

README.md

@@ -1,25 +1,26 @@
 [![Gem Version](https://badge.fury.io/rb/jektex.svg)](https://rubygems.org/gems/jektex)
 
 # Jektex
-Jekyll plugin for blazing fast server side cached LaTeX rendering with support of macros.
-Enjoy comfort of latex and markdown without cluttering your site with bloated javascript.
+A Jekyll plugin for blazing-fast server-side cached LaTeX rendering, with support for macros.
+Enjoy the comfort of LaTeX and Markdown without cluttering your site with bloated JavaScript.
 
 ## Features
 - Renders LaTeX formulas during Jekyll rendering
-- Works without any javascript on clients side
-- Is faster than any other server side Jekyll latex renderer
-- Supports user defined global macros
-- Has I/O efficient caching system
-- Has dynamic and informative log during rendering
-- Is easy to setup
-- Does not interfere with Jekyll workflow and project structure
-- Marks invalid syntax in document with dynamic error highlighting
-- Prints location of invalid expression during rendering
-- Highly configurable but still having sensible defaults
+- Works without any client-side JavaScript
+- Is faster than any other server-side Jekyll LaTeX renderer
+- Supports user-defined global macros
+- Has I/O-efficient caching system
+- Dynamically informs about the number of expressions during rendering
+- Is very easy to setup
+- Doesn't interfere with Jekyll workflow and project structure
+- Marks invalid expressions in document, printing its location during rendering
+- Is highly configurable with sensible defaults
 - Makes sure that cache does not contain expression rendered with outdated configuration
 
 ## Usage
 
+Jektex supports both the built-in Kramdown math notation, and the newer LaTeX-only math notation.
+
 ### Kramdown notation
 **Inline formula**  
 Put formula between two pairs of dolar signs (`$$`) inside of paragraph.
@@ -29,7 +30,7 @@ adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliq
 ```
 
 **Display formula**  
-Put formula between two pairs of dolar sings (`$$`) and surround it by two empty lines.
+Put formula between two pairs of dolar sings (`$$`) and surround it with two empty lines.
 ```latex
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
 incididunt ut labore et dolore magna aliqua.
@@ -48,15 +49,16 @@ so I decided to respect this convention. It makes this plugin more consistent an
 
 ### LaTex math mode notation
 **Inline formula**  
-Put formula between two escaped brackets `\(` `\)`. Its position in a text does not matter.
+Put formula between two escaped brackets `\(` `\)`.
+Its position in the text does not matter.
 ```latex
 Lorem ipsum dolor sit amet, consectetur \(e^{i\theta}=\cos(\theta)+i\sin(\theta)\)
 adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 ```
 
 **Display formula**  
-Put formula between two escaped square brackets `\[` `\]`. Its position in a text does 
-not matter.
+Put formula between two escaped square brackets `\[` `\]`.
+Its position in the text does not matter.
 ```latex
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
 incididunt ut labore et dolore magna aliqua.
@@ -68,62 +70,59 @@ ea commodo consequat.
 ```
 
 ### Config
-Jektex si highly configurable from your `_config.yml` file
+Jektex si highly configurable via your `_config.yml` file.
 
 **Disabling cache**  
-You can disable caching with `disable_disk_cache = true` in `_config.yml`. Cache is
-enabled by default. You can find more information on [Jekyll official website](https://jekyllrb.com/docs/configuration/options/).
+You can disable caching with `disable_disk_cache = true` in `_config.yml`.
+Caching is enabled by default.
+You can find more information on [Jekyll's official website](https://jekyllrb.com/docs/configuration/options/).
 
 **Setting cache location**  
-By default jektex cache will be saved in `.jekyll-cache` directory. This results in it's
-deletion when you call `jekyll clean`. To prevent cache deletion or you just want to
-change location of cache for another reason you can achieve that by specifying
-`cache_dir` in `_config.yml`.
+By default, Jektex cache will be saved in `.jekyll-cache` directory.
+This results in its deletion when you call `jekyll clean`.
+To prevent cache deletion or to change the cache location, you can specify `cache_dir` in `_config.yml`:
 ```yaml
 # Jektex cache dir location
 jektex:
   cache_dir: ".jektex-cache"
 ```
 
-**Ignore**  
-By default jektex tries to render LaTeX in all files not excluded by Jekyll. But 
-sometimes you get in situation when you do not want to render some files. For example
-_RSS feed_ with excerpts containing LaTeX. As a solution jektex offers `ignore` option.
-You can use conventional wild cards using `*`. For example:
+**Ignoring files**  
+By default, Jektex tries to render LaTeX in all files rendered by Jekyll.
+This can sometimes be undesirable, for example when rendering an _RSS feed_ with excerpts containing LaTeX.
+Jektex solves this by using the `ignore` option:
 ```yaml
 # Jektex ignore files
 jektex:
   ignore: ["*.xml", "README.md", "_drafts/*" ]
 ```
 
-This example configuration ignores all `.xml` files, `README.md` and all files 
-in `_drafts` directory.
+You can use conventional wild cards using `*`.
+This example configuration ignores all `.xml` files, `README.md` and all files in the `_drafts` directory.
 
-Another option for ignoring specific posts is setting `jektex` tag in front matter of
-post to `false`. For example:
+Another way to ignore specific posts is setting the `jektex` attribute in front matter to `false`:
 ```yaml
 ---
-title: "How Jektex works"
+ttle: "How Jektex works"
 category: "Development"
 jektex: false
 layout: post
 ---
 ```
 
-Setting `jektex` tag to `true` or not setting at all will result in jektex rendering LaTeX
-expressions in that post.
+Setting `jektex` tag to `true` or not setting at all will result in Jektex rendering LaTeX expressions in that post.
 
-**Macros**  
-You can define global macros like this:
+**Using macros**  
+You can define global macros:
 ```yaml
 # Jektex macros
 jektex:
   macros:
     - ["\\Q", "\\mathbb{Q}"]
     - ["\\C", "\\mathbb{C}"]
 ```
-And yes you have to escape backlash(`\`) with another backlash. This is caused by
-[yaml definition](https://yaml.org/).
+And yes, you have to escape the backlash (`\`) with another backlash.
+This is due to the [yaml specification](https://yaml.org/).
 
 **Complete examples**  
 Recommended config:
@@ -135,6 +134,7 @@ jektex:
     - ["\\Q", "\\mathbb{Q}"]
     - ["\\C", "\\mathbb{C}"]
 ```
+
 Having no configuration is equivalent to this:
 ```yaml
 jektex:
@@ -147,7 +147,7 @@ jektex:
 This plugin is available as a [RubyGem](https://rubygems.org/gems/jektex).
 
 **Using bundler**  
-Add `jektex` to your `Gemfile` like this:
+Add Jektex to your `Gemfile`:
 ```ruby
 group :jekyll_plugins do
     gem "jektex"
@@ -157,22 +157,23 @@ end
 and run `bundle install`
 
 **Without bundler**  
-Just run `gem install jektex`
+Run `gem install jektex`
 
 **After installation**  
-Add jektex to your plugin list in your `_config.yml` file:
+Add Jektex to your plugin list in your `_config.yml` file
 ```yaml
 plugins:
     - jektex
 ```
 
-and do not forget to add `katex.min.css` to you html head:
+and don't forget to add `katex.min.css` to you HTML head:
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css" integrity="sha384-MlJdn/WNKDGXveldHDdyRP1R4CTHr3FeuDNfhsLPYrq2t0UBkUdK2jyTnXPEK1NQ" crossorigin="anonymous">
 ```
-It is much better practice to download [**css** file](https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css) and load it as an asset from your server directly.
+It is much better practice to download the [**css** file](https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css) and load it as an asset from your server directly.
 You can find more information on [KaTeX's website](https://katex.org/docs/browser.html).
 
 ## Contributions and bug reports
 Feel free to repost any bugs or even make feature request in [issues on official repository](https://github.com/yagarea/jektex/issues).
 I am opened for pull requests as well.
+