diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/docs/01-hardware.md b/docs/01-hardware.md new file mode 100644 index 00000000..2d1c283e --- /dev/null +++ b/docs/01-hardware.md @@ -0,0 +1,152 @@ +Hasp-lvgl supports the ESP32, ESP8266 and STM32F4 families of microcontrollers. +It needs a compatible micro-controller with drivers supporting the attached display, touch controller, storage and network. + +Below is a list of recommended development boards and a TFT touchscreen to get you up-and-running in no time. + +## Recommended Boards + + +| | Basic | Standard | Pro | Experimental | +|:-----------|:-----------:|:------------:|:------------:|:------------:| +| MCU | ESP8266 | ESP32-WROOM | ESP32-WROVER | STM32F4 | +| CPU Freq. | 80Mhz | 240Mhz | 240Mhz | 168 MHz | +| Ram | 80Kb | 520Kb | 520Kb | 192Kb | +| PSRam | no | no | yes | no | +| Minimal Flash | 4MB | 4MB | 4MB | 512Kb | +| Display | ILI9341 SPI | ILI9341 SPI | ILI9341 SPI | ILI9341 FSMC | +| Touch | XPT2046 SPI | XPT2046 SPI | XPT2046 SPI | XPT2046 SPI | +| Network | Wifi | Wifi | Wifi | Ethernet / Wifi | +| Dev. Board*|[D1 mini ESP8266][3]|[D1 mini ESP32][4]|[TTGO T7 v1.4 Mini32][5]| STM32F407VET/ZGT Black | +| Firmware | [Download][1] | [Download][1] | [Download][1] | | + +[1]: ./installation.md +[3]: https://www.aliexpress.com/item/32643142716.html +[4]: https://www.aliexpress.com/item/32815530502.html +[5]: https://www.aliexpress.com/item/32977375539.html + +!> \* *Due to the large number of possible hardware options a selection of 3 popular ESP development boards has been made for the precompiled binaries.* + +> **Note:**
Advanced users can build and compile custom configurations using PlatformIO, however this is not currently supported. + + +## Recommended Display +#### Lolin TFT 2.4" + +ILI9341 SPI touchscreens with backlight dimming via PWM are quite cheap to get. +An ILI9341 TFT display with SPI is required when using a pre-built binary. +The touchcontroller needs to be the XPT2046 Resistive Touch driver. + +The Lolin TFT 2.4" is **plug-and-play** with the 3 recommended ESP development boards. +If you have another ESP or MCU, you can still use this display using jumper cables. +You can also solder a row of headers at the bottom of the display to plug it into a breadboard. +Therefor the Lolin TFT 2.4 Touch Shield is used as the development display of choice. + +##### Backlight Control + +To use PWM dimming on the Lolin TFT 2.4" you must solder the TFT-LED pin to either D1, D2 or D4. +**D1 is recommended** for backlight control and configured by default. + +![TFT-LED PWM dimming](https://github.com/fvanroie/hasp-lvgl/blob/master/docs/img/tft-led-pwm.png) + +**Warning** Do *not* use D3 for backlight control because it is already in use for touch! +{: .notice--warning} + +**Note** It is also *not* recommended to use D4 for backlight control because it is already in use for PSram on the ESP32-Wrover. +{: .notice--info} + +##### Compatible ESP boards + +The Lolin TFT 2.4" header is **plug-and-play** compatible with these development boards, +no need to use any jumper cables: + +**ESP32:** +- Wemos D1 Mini ESP32 *(**only** solder the inner row of the pinheaders)* +- TTGO T7 V1.4 MINI32 ESP32 *(**only** solder the inner row of the pinheaders)* +- LOLIN D32 Pro V2.0.0 *using an **additional** TFT cable* + +**ESP8266:** +- Wemos D1 Mini ESP8266 +- Lolin D1 Mini Pro ESP8266 V2.0.0 + +> **Note:**
If you have a Lolin TFT 2.4" Display and a compatible ESP development board, you have all the hardware that is needed. +> In that case you can skip ahead to the [Firmware Installation](./installation.md). + +## Alternative SPI Display + +Any common ILI9341 320x240 4-wire SPI touchscreen with XPT2046 Resistive Touch driver can be used, like: +- 2.4" SKU: MSP2402 +- 2.8" SKU: MSP2807 +- 3.2" SKU: MSP3218 + +You will need to connect the GPIO pins using jumper wires. + +## Experimental MCUs + +#### STM32F407xxT Black Combo + +There are several cheap STM32F407xx Black boards available on the market with a TFT display header +and accompanying 3.2" ILI9341 FSMC screen (320x240). This hardware is experimental and not fully supported. + +
+ + + + + + +
Selection of STM32F407 boards.
+
+ +**Warning** Make sure to purchase a compatible screen, preferably from the same vendor. +There are multiple FSMC interfaces: e.g. One is marked `TFT`, another is marked `New-TFT` and +a third has no markings. +The pinout of each header & display is different and are **not** interchangable! +
You can however use jumper cables instead, but it won't be plug-and-plug anymore. +{: .notice--warning} + +The following boards are being tested: + +- STM32F407VET6 Black (v2.1) with 512 KB flash +
+ + + +
STM32F407VET6 Black (v2.0 and v2.1)
+
+ - Purchase Link: + [AliExpress](https://www.aliexpress.com/item/32618222721.html) + [AliExpress](https://www.aliexpress.com/item/33013274704.html) + [AliExpress](https://www.aliexpress.com/item/1000006481553.html) (! V2.0 !) + - Documentation can be found on [GitHub](https://github.com/mcauser/BLACK_F407VE) + +- STM32F407ZGT6 Black (V3.0) with 1 MB flash +
+ + + +
STM32F407ZGT6 Black (v3.0)
+
+ - Purchase Link: + - Documentation can be found on [GitHub](https://github.com/mcauser/BLACK_F407ZG) + + +**Info** The STM32F4 boards do not have network connectivity. You can use a compatible network adapter and configure it in PlatformIO. +{: .notice--info} + +Images of STM32 boards are [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) from https://stm32-base.org/ \ No newline at end of file diff --git a/docs/01-quick-start-guide.md b/docs/01-quick-start-guide.md new file mode 100644 index 00000000..ad3f4be1 --- /dev/null +++ b/docs/01-quick-start-guide.md @@ -0,0 +1,100 @@ +--- +title: "Quick-Start Guide" +permalink: /projects/hasp-lvgl/quick-start-guide/ +excerpt: "How to quickly install and setup Minimal Mistakes for use with GitHub Pages." +last_modified_at: 2020-04-27 +redirect_from: + - /theme-setup/ +toc: true +--- + +Minimal Mistakes has been developed as a [Gem-based theme](http://jekyllrb.com/docs/themes/) for easier use, and 100% compatible with GitHub Pages when used as a remote theme. + +**If you enjoy this software, please consider [supporting me](https://www.paypal.me/netwize) for developing and maintaining it.** + +[![Support via PayPal](https://cdn.jsdelivr.net/gh/twolfson/paypal-github-button@1.0.0/dist/button.svg)](https://www.paypal.me/mmistakes) + +## Installing the theme + +If you're running Jekyll v3.5+ and self-hosting you can quickly install the theme as a Ruby gem. + +[^structure]: See [**Structure** page]({{ "/docs/structure/" | relative_url }}) for a list of theme files and what they do. + +**ProTip:** Be sure to remove `/docs` and `/test` if you forked Minimal Mistakes. These folders contain documentation and test pages for the theme and you probably don't want them littering up your repo. +{: .notice--info} + +**Note:** The theme uses the [jekyll-include-cache](https://github.com/benbalter/jekyll-include-cache) plugin which will need to be installed in your `Gemfile` and added to the `plugins` array of `_config.yml`. Otherwise you'll throw `Unknown tag 'include_cached'` errors at build. +{: .notice--warning} + + + +### Firmware + +Remote themes are similar to Gem-based themes, but do not require `Gemfile` changes or whitelisting making them ideal for sites hosted with GitHub Pages. + +To install as a remote theme: + +1. Create/replace the contents of your `Gemfile` with the following: + + ```ruby + source "https://rubygems.org" + + gem "github-pages", group: :jekyll_plugins + ``` + +2. Add `jekyll-include-cache` to the `plugins` array of your `_config.yml`. + +3. Fetch and update bundled gems by running the following [Bundler](http://bundler.io/) command: + + ```bash + bundle + ``` + +4. Add `remote_theme: "mmistakes/minimal-mistakes@4.19.2"` to your `_config.yml` file. Remove any other `theme:` or `remote_theme:` entry. + +You may also optionally specify a branch, [tag](https://github.com/mmistakes/minimal-mistakes/tags), or commit to use by appending an @ and the Git ref (e.g., `mmistakes/minimal-mistakes@4.9.0` or `mmistakes/minimal-mistakes@bbf3cbc5fd64a3e1885f3f99eb90ba92af84063d`). This is useful when rolling back to older versions of the theme. If you don't specify a Git ref, the latest on `master` will be used. + +**Looking for an example?** Use the [Minimal Mistakes remote theme starter](https://github.com/mmistakes/mm-github-pages-starter/generate) for the quickest method of getting a GitHub Pages hosted site up and running. Generate a new repository from the starter, replace sample content with your own, and configure as needed. +{: .notice--info} + +--- + +**Note:** Your Jekyll site should be viewable immediately at . If it's not, you can force a rebuild by **Customizing Your Site** (see below for more details). +{: .notice--warning} + +If you're hosting several Jekyll based sites under the same GitHub username you will have to use Project Pages instead of User Pages. Essentially you rename the repo to something other than **USERNAME.github.io** and create a `gh-pages` branch off of `master`. For more details on how to set things up check [GitHub's documentation](https://help.github.com/articles/user-organization-and-project-pages/). + +
+ creating a new branch on GitHub +
+ +You can also install the theme by copying all of the theme files[^structure] into your project. + +To do so fork the [Minimal Mistakes theme](https://github.com/mmistakes/minimal-mistakes/fork), then rename the repo to **USERNAME.github.io** --- replacing **USERNAME** with your GitHub username. + +
+ fork Minimal Mistakes +
+ +**GitHub Pages Alternatives:** Looking to host your site for free and install/update the theme painlessly? [Netlify][netlify-jekyll], [GitLab Pages][gitlab-jekyll], and [Continuous Integration (CI) services][ci-jekyll] have you covered. In most cases all you need to do is connect your repository to them, create a simple configuration file, and install the theme following the [Ruby Gem Method](#ruby-gem-method) above. +{: .notice--info} + +[netlify-jekyll]: https://www.netlify.com/blog/2015/10/28/a-step-by-step-guide-jekyll-3.0-on-netlify/ +[gitlab-jekyll]: https://about.gitlab.com/2016/04/07/gitlab-pages-setup/ +[ci-jekyll]: https://jekyllrb.com/docs/continuous-integration/ + +### Minimal Configuration + +You need to setup network connectivity to your network and connect to an MQTT broker service. + +## Home Automation + +There are some examples available to help you integrate HASP into your Home Automation setup: +- Home Assistant +- OpenHAB +- Node-RED +- Tasmota Slave + +**ProTip:** The source code and content files for this site can be found in the [`/docs` folder](https://github.com/mmistakes/minimal-mistakes/tree/master/docs) if you want to copy or learn from them. +{: .notice--info} + diff --git a/docs/02-installation.md b/docs/02-installation.md new file mode 100644 index 00000000..6137b3a9 --- /dev/null +++ b/docs/02-installation.md @@ -0,0 +1,82 @@ +## Download the firmware + +Go to the releases page on Github to download the latest hasp-lvgl binaries. + +[ Hasp-lvgl Releases](https://github.com/fvanroie/hasp-lvgl/releases){: .btn .btn--info} + +There are currently 2 download options, pick the one appropriate for your hardware: +- hasp-lvgl-0.2.0-esp32_ili9341_spi.bin +- hasp-lvgl-0.2.0-esp8266_ili9341_spi.bin + boot files + +> If no precompiled firmware file is available for your board you can configure, compile and upload the firmware yourself using PlatformIO. +{: .notice--info} + + +## Install the firmware + +### Flash ESP32 + +When flashing the ESP32 for the first time, you need to install a bootloader, partitionscheme and application loader: +```shell +esptool.py --port "COM1" erase_flash +esptool.py --port "COM1" write_flash 0x1000 bootloader_dio_40m.bin --flash_mode dio --flash_freq 40m +esptool.py --port "COM1" write_flash 0x8000 partitions.bin +esptool.py --port "COM1" write_flash 0xe000 boot_app0.bin +``` + +Change `COM1` to the correct port on your computer. + +then flash the actual firmware: + +```shell +esptool.py -p "COM1" --baud 921600 write_flash 0x10000 d1-mini-esp32_ili9341_.bin +``` + +or all previous steps in one long commandline: + +```shell +esptool.py -p "COM1" --baud 921600 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader_dio_40m.bin 0x8000 partitions.bin 0xe000 boot_app0.bin 0x10000 d1-mini-esp32_ili9341_.bin +``` + +### Flash ESP8266 + +Unlike the ESP32, for ESP8266 you only need one single `.bin` file: + +#### Using Tasmotizer (Windows) + +#### Using esp-tool.py + +```shell +esptool.py -p "COM1" write_flash --flash_mode qio --flash_size 4m 0x0 d1-mini-esp8266_ili9341_.bin +``` + +Change `COM1` to the correct port on your computer and `4m` to the correct size of the internal flash chip. + +---------------------------------------------------------------------------------- + +### STM32F407 devEbox + +**Note** There is no precompiled firmware file available for STM32F4 boards. You will need to configure, compile and upload the firmware yourself using PlatformIO. +{: .notice--info} + +#### Using Serial + +- Connect your serial TTL adapter RX and TX pins to PA9 and PA10 of the devEbox. +- Place the boot jumpers into programming mode +- Reset the board. +- Upload the firmware using: + +#### Using DFU (USB) + +- Connect your serial TTL adapter RX and TX pins to PA9 and PA10 of the devEbox. +- Place the boot jumpers into programming mode +- Reset the board. +- Upload the firmware using: + +#### Using ST Link (USB) + +- Install ST Link software +- Connect the devEbox using the USB port +- Launch ST Link +- Select the hasp-lvgl-0.2.0-stm32f407_devEbox_3.2_ili9341_fsmc.bin file +- Flash the firmware to the board \ No newline at end of file diff --git a/docs/03-wifi-setup.md b/docs/03-wifi-setup.md new file mode 100644 index 00000000..892cf2bd --- /dev/null +++ b/docs/03-wifi-setup.md @@ -0,0 +1,42 @@ +At first boot, when no wifi setup is found, the device will create an initial Access Point for configuring the device. +If the touchscreen is properly connected it will display a QR code, along with a temporary SSID and password, to connect to the device. + +
+ + + +
+ +Either use the touchscreen interface or connect via a webbrowser to setup the credentials for your local wifi access point: + +## Using Touchscreen + +1. Tap on the screen to start a Touch Calibration sequence: +2. Precisely touch the 4 courners as indicated +3. Use the on-screen keyboard to enter your local SSID and password + - Tap on the Checkmark button in the lower righthand corner to save the settings + +The device will validate the entered credentials and reboot if they are correct. + +## Using WiFi Access-Point + +Connect to the temporary Access Point by scanning the QR on the display, if available. +Or Check the serial log for the SSID and password to connect. + +- Browse to http://192.168.4.1 +- Enter your local SSID and password for joining the device to your wireless network +- Click Save Settings +- The device will automatically reboot and connect to your wireless LAN + +## Using Command line + +You can also directly configure the wifi settings via the serial console: + +```bash +ssid myAccessPointName +pass myWifiPassword +reboot +``` + +> **Note:**
To skip this step, wifi credentials can be saved into the .bin file when you compile the firmware yourself. + diff --git a/docs/05-commands.md b/docs/05-commands.md new file mode 100644 index 00000000..cbd2ce8a --- /dev/null +++ b/docs/05-commands.md @@ -0,0 +1,150 @@ +Commands are not related to an object, but can get or set global properties or invoke system commands on the device. + +Commands can be issued via the Serial Commandline, Telnet Commandline or MQTT. +For MQTT, use the `hasp//command` topic with payload ` ` + +Here is a list of all the recaognized command keywords: + +## Pages + +`page` [0-11] + +Switches the display to show the objects from a diferent page. + +`clearpage` [0-11,254] + +Deletes all objects on a given page. If no page number is specified, it clears the current page. + +To delete individual objects, you can issue the `p[x].b[y].delete` command. + +## Backlight + +`dim` [0-100] (alias: `brightness`) + +Sets the level of the backlight from 0 to 100%, where 0% is off and 100% is full brightness. + +Example: `dim 50` sets the display to half the brightness. + +Tip: this can be used in conjunction with the idle event e.g. to dim the backlight after a short period of inactivity. + +`light` + +Switches the backlight on or off, independent of the set dim level. +Turning the backlight on will restore the brightness to the previous dim level. + +Example: `light on` acepted values: on/off, true/false, 0/1, yes/no + +Tip: this can be used in conjunction with the idle event, e.g. to turn the backlight off after a long period of inactivity. + +Note: The `dim`and `light` command depends on a GPIO pin to be connected to control the the TFT_LED backlight via a transistor. + +`wakeup` + +Clears the idle state of the device and publishes an `state/idle = OFF` status message. It resets the idle counter as if a touch event occured on the devide. This is helpfull e.g. when you want to wake up the display when an external event has occured, like a PIR motion sensor. + +## System commands + +`calibrate` + +Start on-screen touch calibration. + +Note: You need to issue a soft reboot command to save the new calibration settings. If you do a hard reset of the device, the calibration settings will be lost. + +`screenshot` + +Saves a picture of the current screen to the flash filesystem. You can retrieve it via http://>ip-address</screenshot.bmp +This can be handy for bug reporting or documentation. + +The previous screenshot is overwritten. + +`statusupdate` + +Reports the status of the MCU. The response will be posted to the state topic: +```json + "statusupdate": { + "status": "available", + "espVersion": "0.0.6", + "espUptime": 124, + "signalStrength": -72, + "haspIP": "10.1.0.148", + "heapFree": 5912, + "heapFragmentation": 7, + "espCore": "2_6_3" + } +``` + +`reboot` (alias: `restart`) + +Saves any changes in the configuration file and reboots the device. + +`factoryreset` + +Clear the filesystem and eeprom and reboot the device in its initial state. + +Warning: There is no confirmation prompt nor undo function! + +## Configuration Settings + +### Wifi + +`ssid` + +Sets network name of the access point to connect to. + +`pass` + +Sets the optional password for the access point to connect to. + +### MQTT + +`hostname` + +Sets the hostname of the device and mqtt topic for the node to `hasp//` + +`mqtthost` + +Sets the hostname of the mqtt broker. + +`mqttport` + +Sets the port of the mqtt broker. + +`mqttuser` + +Sets the optional username for the mqtt broker. + +`mqttpass` + +Sets the optional password for the mqtt broker. + +### Config/xxx + +You can get or set the configuration of a hasp-lvgl submodule in json format. +To get the configuration, the command `config/>submodule<`. +The result will be published to `hasp/plate35/state/config`. Passwords will be omited from the result. + +``` +config/wifi +config/mqtt +config/http +config/mdns +config/hasp +config/gui +config/debug +``` + +To update the configuration simple issue the same command `config/>submodule<` with updated json payload. + +## Multiple Commands + +`json` + +When you want to execute multiple commands in one payload, you can use the json command to create an array of commands. + +Each command is an element in this array of strings: + +```json +["page 5","dim 50","light on","statusupdate"] +``` + +The commands are interpreted and processed sequentially. \ No newline at end of file diff --git a/docs/05-configuration.md b/docs/05-configuration.md new file mode 100644 index 00000000..ab8b5c87 --- /dev/null +++ b/docs/05-configuration.md @@ -0,0 +1,1067 @@ +Settings that affect your entire site can be changed in [Jekyll's configuration file](https://jekyllrb.com/docs/configuration/): `_config.yml`, found in the root of your project. If you don't have this file you'll need to copy or create one using the theme's [default `_config.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_config.yml) as a base. + +**Note:** for technical reasons, `_config.yml` is NOT reloaded automatically when used with `jekyll serve`. If you make any changes to this file, please restart the server process for them to be applied. +{: .notice--warning} + +Take a moment to look over the configuration file included with the theme. Comments have been added to provide examples and default values for most settings. Detailed explanations of each can be found below. + +## Site settings + +### Theme + +If you're using the Ruby gem version of the theme you'll need this line to activate it: + +```yaml +theme: minimal-mistakes-jekyll +``` + +### Skin + +Easily change the color scheme of the theme using one of the provided "skins": + +```yaml +minimal_mistakes_skin: "default" # "air", "aqua", "contrast", "dark", "dirt", "neon", "mint", "plum" "sunrise" +``` + +**Note:** If you have made edits to the theme's CSS files be sure to update [`/assets/css/main.scss`](https://github.com/mmistakes/minimal-mistakes/blob/master/assets/css/main.scss) to include `@import "minimal-mistakes/skins/{{ site.minimal_mistakes_skin | default: 'default' }}"; // skin` before the `minimal-mistakes` import. +{: .notice--warning} + +#### Air skin: `air` + +{:.no_toc} + +
+ + +
Calm and blue.
+
+ +#### Aqua skin: `aqua` + +
+ + +
Just like water.
+
+ +#### Contrast skin: `contrast` + +
+ + +
Retro feel with bold blue links and inverted footer.
+
+ +#### Dark skin: `dark` + +
+ + +
Inverted palette, white text on a dark background.
+
+ +#### Dirt skin: `dirt` + +
+ + +
Earthy tones.
+
+ +#### Mint skin: `mint` + +{:.no_toc} + +
+ + +
Minty fresh green.
+
+ +#### Neon skin: `neon` + +
+ + +
Inverted palette, white text on a dark background.
+
+ +#### Neon skin: `plum` + +
+ + +
Purple reigns supreme.
+
+ +#### Sunrise skin: `sunrise` + +
+ + +
Oranges and red.
+
+ +### Site locale + +`site.locale` is used to declare the primary language for each web page within the site. + +_Example:_ `locale: "en-US"` sets the `lang` attribute for the site to the _United States_ flavor of English, while `en-GB` would be for the `United Kingdom` style of English. Country codes are optional and the shorter variation `locale: "en"` is also acceptable. To find your language and country codes check this [reference table](). + +Properly setting the locale is important for associating localized text found in the [**UI Text**]({{ "/docs/ui-text/" | relative_url }}) data file. An improper match will cause parts of the UI to disappear (eg. button labels, section headings, etc). + +**Note:** The theme comes with localized text in English (`en`, `en-US`, `en-GB`). If you change `locale` in `_config.yml` to something else, most of the UI text will go blank. Be sure to add the corresponding locale key and translated text to `_data/ui-text.yml` to avoid this. +{: .notice--warning} + +### Site title + +The name of your site. Is used throughout the theme in places like the site masthead and `` tags. + +_Example:_ `title: "My Awesome Site"` + +You also have the option of customizing the separation character used in SEO-friendly page titles. + +_Example:_ `title_separator: "|"` would produce page titles like `Sample Page | My Awesome Site`. + +**Note:** Long site titles have been known to break the masthead layout. Avoid adding a long "tagline" to the title prevent this from happening eg. `My Awesome Site is the Best Because I Say So". +{: .notice--warning} + +### Site subtitle + +A short tagline that appears below the title in site masthead. + +_Example:_ `subtitle: "Version 2.0"` + +### Site name + +Used to assign a site author. Don't worry, you can override the site author with different ones on specific posts, pages, or collection documents. + +_Example:_ `name: "Michael Rose"`. + +**ProTip:** If you want to get crafty with your YAML you can use [anchors](http://www.yaml.org/spec/1.2/spec.html#id2785586) to reuse values. For example `foo: &var "My String"` allows you to reuse `"My String"` elsewhere in `_config.yml` like so... `bar: *var`. You'll see a few examples of this in the provided Jekyll config. +{: .notice--info} + +### Site description + +Fairly obvious. `site.description` describes the site. Used predominantly in meta descriptions for improving SEO. + +_Example:_ `description: "A flexible Jekyll theme for your blog or site with a minimalist aesthetic."` + +### Site URL + +The base hostname and protocol for your site. If you're hosting with GitHub Pages this will be something like `url: "https://mmistakes.github.io"` or `url: "https://mademistakes.com"` if you have a custom domain name. + +GitHub Pages now [forces `https://` for new sites](https://help.github.com/articles/securing-your-github-pages-site-with-https/) so be mindful of that when setting your URL to avoid mixed-content warnings. + +**Note:** Jekyll 3.3 overrides this value with `url: http://localhost:4000` when running `jekyll serve` locally in development. If you want to avoid this behavior set `JEKYLL_ENV=production` to [force the environment](http://jekyllrb.com/docs/configuration/#specifying-a-jekyll-environment-at-build-time) to production. +{: .notice--warning} + +### Site base URL + +This little option causes all kinds of confusion in the Jekyll community. If you're not hosting your site as a GitHub Pages Project or in a subfolder (eg: `/blog`), then don't mess with it. + +In the case of the Minimal Mistakes demo site it's hosted on GitHub at <https://mmistakes.github.io/minimal-mistakes>. To correctly set this base path I'd use `url: "https://mmistakes.github.io"` and `baseurl: "/minimal-mistakes"`. + +For more information on how to properly use `site.url` and `site.baseurl` as intended by the Jekyll maintainers, check [Parker Moore's post on the subject](https://byparker.com/blog/2014/clearing-up-confusion-around-baseurl/). + +**Note:** When using `baseurl` remember to include it as part of your path when testing your site locally. Values of `url:` and `baseurl: "/blog"` would make your local site visible at `http://localhost:4000/blog` and not `http://localhost:4000`. +{: .notice--warning} + +### Site repository + +Add your repository name with organization to your site's configuration file, `_config.yml`. + +```yaml +repository: "username/repo-name" +``` + +"NWO" stands for "name with owner." It is GitHub lingo for the username of the owner of the repository plus a forward slash plus the name of the repository, e.g. `mmistakes/minimal-mistakes`, where **mmistakes** is the owner and **minimal-mistakes** is the repository name. + +Your `site.github.*` fields should fill in like normal. If you run Jekyll with the --verbose flag, you should be able to see all the API calls made. + +If you don't set `repository` correctly you may see the following error when trying to `serve` or `build` your Jekyll site: + +**Liquid Exceptions:** No repo name found. Specify using `PAGES_REPO_NWO` environment variables, `repository` in your configuration, or set up `origin` git remote pointing to your github.com repository. +{: .notice--danger} + +For more information on how `site.github` data can be used with Jekyll check out [`github-metadata`'s documentation](https://github.com/jekyll/github-metadata). + +### Site scripts + +Add scripts to the `<head>` or closing `</body>` elements by assigning paths to either `head_scripts` and/or `footer_scripts`. + +For example, to add a CDN version of jQuery to page's head along with a custom script you'd do the following: + +```yaml +head_scripts: + - https://code.jquery.com/jquery-3.2.1.min.js + - /assets/js/your-custom-head-script.js +``` + +Consult the [JavaScript documentation]({{ site.baseurl }}{% link _hasp/17-javascript.md %}) for more information on working with theme scripts. +{: .notice--info} + +### Site default teaser image + +To assign a fallback teaser image used in the "**Related Posts**" module, place a graphic in the `/assets/images/` directory and add the filename to `_config.yml` like so: + +```yaml +teaser: /assets/images/500x300.png +``` + +This image can be overridden at anytime by applying the following to a document's YAML Front Matter. + +```yaml +header: + teaser: /assets/images/my-awesome-post-teaser.jpg +``` + +<figure> + <img src="{{ '/assets/images/mm-teaser-images-example.jpg' | relative_url }}" alt="teaser image example"> + <figcaption>Example of teaser images found in the related posts module.</figcaption> +</figure> + +### Site masthead logo + +To insert a logo before the site title, place a graphic in the `/assets/images/` directory and add the filename to `_config.yml`: + +```yaml +logo: "/assets/images/88x88.png" +``` + +<figure> + <img src="{{ '/assets/images/mm-masthead-logo.png' | relative_url }}" alt="masthead with logo and custom title"> + <figcaption>Example of masthead with logo and custom title.</figcaption> +</figure> + +### Site masthead title + +By default your site title is used in the masthead. You can override this text by adding the following to your `_config.yml`: + +```yaml +masthead_title: "My Custom Title" +``` + +### Breadcrumb navigation (beta) + +Enable breadcrumb links to help visitors better navigate deep sites. Because of the fragile method of implementing them they don't always produce accurate links reliably. For best results: + +1. Use a category based permalink structure e.g. `permalink: /:categories/:title/` +2. Manually create pages for each category or use a plugin like [jekyll-archives][jekyll-archives] to auto-generate them. If these pages don't exist breadcrumb links to them will be broken. + +![breadcrumb navigation example]({{ "/assets/images/mm-breadcrumbs-example.jpg" | relative_url }}) + +```yaml +breadcrumbs: true # disabled by default +``` + +Breadcrumb start link text and separator character can both be changed in the [UI Text data file]({{ "/docs/ui-text/" | relative_url }}). + +### Reading time + +Enable estimated reading time snippets with `read_time: true` in YAML Front Matter. `200` has been set as the default words per minute value --- which can be changed by adjusting `words_per_minute:` in `_config.yml`. + +![reading time example]({{ "/assets/images/mm-read-time-example.jpg" | relative_url }}) + +Instead of adding `read_time: true` to each post, apply as a default in `_config.yml` like so: + +```yaml +defaults: + # _posts + - scope: + path: "" + type: posts + values: + read_time: true +``` + +To disable reading time for a post, add `read_time: false` its YAML Front Matter to override what was set in `_config.yml`. + +`words_per_minute` can also be adjusted per-page basis by adding to its YAML Front Matter. This is useful for sites with multi-lingual content where you'd like specify a different value from the site config. + +```yaml +words_per_minute: 250 +``` + +### Comments + +[**Disqus**](https://disqus.com/), [**Discourse**](https://www.discourse.org/), [**Facebook**](https://developers.facebook.com/docs/plugins/comments), [**utterances**](https://utteranc.es/), and static-based commenting via [**Staticman**](https://staticman.net/) are built into the theme. First set the comment provider you'd like to use: + +| Name | Comment Provider | +| ---------------- | ------------------------- | +| **disqus** | Disqus | +| **discourse** | Discourse | +| **facebook** | Facebook Comments | +| **staticman_v2** | Staticman v2 | +| **staticman** | Staticman v1 (deprecated) | +| **utterances** | utterances | +| **custom** | Other | + +Then add `comments: true` to each document you want comments visible on. + +Instead of adding YAML Front Matter to each document, apply as a default in `_config.yml`. To enable comments for all posts: + +```yaml +defaults: + # _posts + - scope: + path: "" + type: posts + values: + comments: true +``` + +If you add `comments: false` to a post's YAML Front Matter it will override the default and disable comments for just that post. + +**Note:** Comments are disabled by default in `development`. To enable when testing/building locally be sure to set +`JEKYLL_ENV=production` to [force the environment](http://jekyllrb.com/docs/configuration/#specifying-a-jekyll-environment-at-build-time) to production. +{: .notice--info} + +#### Disqus + +To use Disqus you'll need to create an account and [shortname](https://help.disqus.com/customer/portal/articles/466208-what-s-a-shortname-). Once you have both update `_config.yml` to: + +```yaml +comments: + provider: "disqus" + disqus: + shortname: "your-disqus-shortname" +``` + +#### Discourse + +For guidance on how to set up Discourse for embedding comments from a topic on a post page, [consult this guide](https://meta.discourse.org/t/embedding-discourse-comments-via-javascript/31963). + +```yaml +comments: + provider: "discourse" + discourse: + server: # meta.discourse.org +``` + +**Note:** Do not include `http://` or `https://` when setting your Discourse `server`. The theme automatically prepends the URL `//`, following a scheme-less pattern. +{: .notice--info} + +#### Facebook comments + +To enable Facebook Comments choose how many comments you'd like visible per post and the color scheme of the widget. + +```yaml +comments: + provider: "facebook" + facebook: + appid: # optional + num_posts: # 5 (default) + colorscheme: # "light" (default), "dark" +``` + +#### utterances comments + +To use utterances you will need to [install the app](https://github.com/apps/utterances) to your GitHub repository by adding the following to `_config.yml`: + +```yaml +repository: # GitHub username/repo-name e.g. "mmistakes/minimal-mistakes" +``` + +**Note:** Make sure the repo is public, otherwise your readers will not be able to view the issues/comments. The [issues feature](https://guides.github.com/features/issues/) also needs to be active on your repo. +{: .notice--warning} + +To enable utterances on the front end set `comments.provider` and the color theme of the widget. + +```yaml +comments: + provider: "utterances" + utterances: + theme: "github-light" # "github-dark" + issue_term: "pathname" +``` + +#### Static-based comments via Staticman + +Transform user comments into `_data` files that live inside of your GitHub repository by enabling Staticman. + +**Note:** Looking to migrate comments from a WordPress based site? Give [this tool](https://github.com/arthurlacoste/wordpress-comments-jekyll-staticman) a try. +{: .notice--info} + +**Note:** Please note that as of September 2018, Staticman is reaching GitHub API limits due to its popularity, and it is recommended by its maintainer that users deploy their own instances for production (use `site.staticman.endpoint`). +{: .notice--warning} + +##### Add Staticman as a collaborator + +1. Allow Staticman push access to your GitHub repository by clicking on **Settings**, then the **Collaborators** tab and adding `staticmanapp` as a collaborator. +2. To accept the pending invitation visit: `https://api.staticman.net/v2/connect/{your GitHub username}/{your repository name}`. Consult the Staticman "[Get Started](https://staticman.net/docs/index.html)" guide for more info. + +##### Configure Staticman + +###### Staticman v3 + +Due to the [support for GitLab](https://github.com/eduardoboucas/staticman/pull/219), the URL scheme has been changed. Between `v3/entry/` and `/{your Git username}`, one needs to input a Git service provider (either `github` or `gitlab`). For example + + https://{your Staticman v3 API}/v3/entry/github/{your Git username}/{your repository name}/... + +```yaml +# _config.yml (defaults) +repository : # Git username/repo-name e.g. "mmistakes/minimal-mistakes" +comments: + provider : "staticman_v2" + staticman: + branch : "master" + endpoint : https://{your Staticman v3 API}/v3/entry/github/ +``` + +###### Staticman v2 + +Default settings have been provided in [`staticman.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/staticman.yml) and are commented to guide you through setup. View the [full list of configurations](https://staticman.net/docs/configuration). + +```yaml +# staticman.yml (defaults) +comments: + allowedFields : ["name", "email", "url", "message"] + branch : "master" + commitMessage : "New comment by {fields.name}" + filename : "comment-{@timestamp}" + format : "yaml" + generatedFields: + date: + type : "date" + options: + format : "iso8601" + moderation : true + path : "_data/comments/{options.slug}" + requiredFields : ["name", "email", "message"] + transforms: + email : md5 +``` + +These settings need to be added to your `_config.yml` file as well: + +```yaml +# _config.yml (defaults) +repository : # GitHub username/repo-name e.g. "mmistakes/minimal-mistakes" +comments: + provider : "staticman_v2" + staticman: + branch : "master" +``` + +**Branch setting:** This is the branch comment files will be sent to via pull requests. If you host your site on GitHub Pages it will likely be `master` unless your repo is setup as a project --- use `gh-pages` in that case. +{: .notice--info} + +**Note:** Staticman is currently compatible with GitHub and GitLab based repositories. [Support for GitLab Pages](https://github.com/eduardoboucas/staticman/issues/22) is already available at [Staticman v3](https://github.com/eduardoboucas/staticman/pull/219). +{: .notice--warning} + +###### Staticman v1 (deprecated) + +Default settings have been provided in `_config.yml`. The important ones to set are `provider: "staticman"`, `branch`, and `path`. View the [full list of configurations](https://staticman.net/docs/configuration). + +```yaml +# _config.yml (defaults) +comments: + provider: "staticman" +staticman: + allowedFields : ['name', 'email', 'url', 'message'] + branch : "master" + commitMessage : "New comment by {fields.name}" + filename : comment-{@timestamp} + format : "yml" + moderation : true + path : "_data/comments/{options.slug}" + requiredFields : ['name', 'email', 'message'] + transforms: + email : "md5" + generatedFields: + date: + type : "date" + options: + format : "iso8601" # "iso8601" (default), "timestamp-seconds", "timestamp-milliseconds" +``` + +##### Comment moderation + +By default comment moderation is enabled in `staticman.yml`. As new comments are submitted Staticman will send a pull request. Merging these in will approve the comment, close the issue, and automatically rebuild your site (if hosted on GitHub Pages). + +To skip this moderation step simply set `moderation: false`. + +**ProTip:** Create a GitHub webhook that sends a `POST` request to the following payload URL `https://api.staticman.net/v2/webhook` and triggers a "Pull request" event to delete Staticman branches on merge. +{: .notice--info} + +![pull-request webhook]({{ "/assets/images/mm-staticman-pr-webhook.jpg" | relative_url }}) + +##### reCAPTCHA support (v2 only) + +To enable Google's reCAPTCHA to aid in spam detection you'll need to: + +1. Apply for [reCAPTCHA API](https://www.google.com/recaptcha) keys and register your site using the reCAPTCHA V2 type. +2. Add your site and secret keys to `staticman.yml` and `_config.yml`. Be sure to properly encrypt your secret key using [Staticman's encrypt endpoint](https://staticman.net/docs/encryption). + +```yaml +reCaptcha: + enabled: true + siteKey: # "6LdRBykTAAAAAFB46MnIu6ixuxwu9W1ihFF8G60Q" + secret: # "PznnZGu3P6eTHRPLORniSq+J61YEf+A9zmColXDM5icqF49gbunH51B8+h+i2IvewpuxtA9TFoK68TuhUp/X3YKmmqhXasegHYabY50fqF9nJh9npWNhvITdkQHeaOqnFXUIwxfiEeUt49Yoa2waRR7a5LdRAP3SVM8hz0KIBT4=" +``` + +#### Other comment providers + +To use another provider not included with the theme set `provider: "custom"` then add their embed code to `_includes/comments-providers/custom.html`. + +### Custom feed URL + +By default the theme links to `feed.xml` generated in the root of your site by the **jekyll-feed** plugin. To link to an externally hosted feed update `atom_feed` in `_config.yml` like so: + +```yaml +atom_feed: + path: "http://feeds.feedburner.com/youFeedname" +``` + +**Note:** By default the site feed is linked in two locations: inside the [`<head>` element](https://github.com/mmistakes/minimal-mistakes/blob/master/_includes/head.html) and at the bottom of every page in the [site footer](https://github.com/mmistakes/minimal-mistakes/blob/master/_includes/footer.html). +{: .notice--info} + +### Site search + +To enable site-wide search add `search: true` to your `_config.yml`. + +![masthead search example]({{ "/assets/images/masthead-search.gif" | relative_url }}) + +#### Lunr (default) + +The default search uses [**Lunr**](https://lunrjs.com/) to build a search index of all post and your documents in collections. This method is 100% compatible with sites hosted on GitHub Pages. + +**Note:** Only the first 50 words of a post or page's body content is added to the Lunr search index. Setting `search_full_content` to `true` in your `_config.yml` will override this and could impact page load performance. +{: .notice--warning} + +#### Algolia + +For faster and more relevant search ([see demo](https://mmistakes.github.io/minimal-mistakes-algolia-search/)): + +1. Add the [`jekyll-algolia`](https://github.com/algolia/jekyll-algolia) gem to your `Gemfile`, in the `:jekyll_plugins` section. + + ```ruby + group :jekyll_plugins do + gem "jekyll-feed" + gem "jekyll-seo-tag" + gem "jekyll-sitemap" + gem "jekyll-paginate" + gem "jekyll-include-cache" + gem "jekyll-algolia" + end + ``` + + Once this is done, download all dependencies by running `bundle install`. + +2. Switch search providers from `lunr` to `algolia` in your `_config.yml` file: + + ```yaml + search_provider: algolia + ``` + +3. Add the following Algolia credentials to your `_config.yml` file. *If you don't have an Algolia account, you can open a free [Community plan](https://www.algolia.com/users/sign_up/hacker). Once signed in, you can grab your credentials from [your dashboard](https://www.algolia.com/licensing).* + + ```yaml + algolia: + application_id: # YOUR_APPLICATION_ID + index_name: # YOUR_INDEX_NAME + search_only_api_key: # YOUR_SEARCH_ONLY_API_KEY + powered_by: # true (default), false + ``` + +4. Once your credentials are setup, you can run the indexing with the following command: + + ``` + ALGOLIA_API_KEY=your_admin_api_key bundle exec jekyll algolia + ``` + + For Windows users you will have to use `set` to assigned the `ALGOLIA_API_KEY` environment variable. + + ``` + set ALGOLIA_API_KEY=your_admin_api_key + bundle exec jekyll algolia + ``` + + Note that `ALGOLIA_API_KEY` should be set to your admin API key. + +To use the Algolia search with GitHub Pages hosted sites follow [this deployment guide](https://community.algolia.com/jekyll-algolia/github-pages.html). Or this guide for [deploying on Netlify](https://community.algolia.com/jekyll-algolia/netlify.html). + +**Note:** The Jekyll Algolia plugin can be configured in several ways. Be sure to check out [their full documentation](https://community.algolia.com/jekyll-algolia/options.html "Algolia configuration") on how to exclude files and other valuable settings. +{: .notice--info} + +#### Google Custom Search Engine + +Add a Google search box to your site. + +1. Create a **New search engine** in [Google Custom Search Engine](https://cse.google.com/cse/all), give it an appropriate name and setup "Sites to search" to your liking. + +2. Under **Look and feel** choose the "Results only" layout and a theme (*Minimalist* is a good choice to match the default look of the Minimal Mistakes). + + ![Google Custom Search Engine layout]({{ '/assets/images/google-custom-search-engine-layout.png' | relative_url }}) + +3. Select "Save & Get Code" and grab your search engine ID from the line that begins with `var cx = 'YOUR_SEARCH_ENGINE_ID'`. + +4. Add your search engine ID to `_config.yml` like so: + + ```yaml + google: + search_engine_id: YOUR_SEARCH_ENGINE_ID + ``` + +**Note:** If your site is new and hasn't been indexed by Google yet, search will be incomplete and won't provide accurate results. +{: .notice--info} + +### SEO, social sharing, and analytics settings + +All optional, but a good idea to take the time setting up to improve SEO and links shared from the site. + +#### Google Search Console + +Formerly known as [Google Webmaster Tools](https://www.google.com/webmasters/tools/), add your [verification code](https://support.google.com/analytics/answer/1142414?hl=en) like so: `google_site_verification: "yourVerificationCode"`. + +**Note:** You likely won't have to do this if you verify site ownership through **Google Analytics** instead. +{: .notice--warning} + +#### Bing Webmaster Tools + +There are several ways to [verify site ownership](https://www.bing.com/webmaster/help/how-to-verify-ownership-of-your-site-afcfefc6) --- the easiest adding an authentication code to your config file. + +Copy and paste the string inside of `content`: + +```html +<meta name="msvalidate.01" content="0FC3FD70512616B052E755A56F8952D" /> +``` + +Into `_config.yml` + +```yaml +bing_site_verification: "0FC3FD70512616B052E755A56F8952D" +``` + +#### Naver Webmaster Tools + +To verify site ownership you will need to [create a Naver account](https://nid.naver.com/user2/joinGlobal.nhn?lang=en_US&m=init) and then **Add your site** via [Naver Webmaster Tools](http://webmastertool.naver.com/). + +Much like Google and Bing you'll be provided with a meta description: + +```html +<meta name="naver-site-verification" content="6BF5A01C0E650B479B612AC5A2184144">` +``` + +Which you can add to your `_config.yml` like so: + +```yaml +naver_site_verification: "6BF5A01C0E650B479B612AC5A2184144" +``` + +#### Yandex + +To verify site ownership copy and paste the string inside of `content`: + +```html +<meta name='yandex-verification' content='2132801JL' /> +``` + +Into `_config.yml` + +```yaml +yandex_site_verification: "2132801JL" +``` + +#### Twitter Cards and Facebook Open Graph + +To improve the appearance of links shared from your site to social networks like Twitter and Facebook be sure to configure the following. + +##### Site Twitter username + +Twitter username for the site. For pages that have custom author Twitter accounts assigned in their YAML Front Matter or data file, they will be attributed as a **creator** in the Twitter Card. + +For example if my site's Twitter account is `@mmistakes-theme` I would add the following to `_config.yml` + +```yaml +twitter: + username: "mmistakes-theme" +``` + +And if I assign `@mmistakes` as an author account it will appear in the Twitter Card along with `@mmistakes-theme`, attributed as a creator of the page being shared. + +**Note**: You need to validate cards are working and have Twitter [approve Player Cards](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/player-card) before they will begin showing up. +{: .notice--warning} + +##### Facebook Open Graph + +If you have a Facebook ID or publisher page add them: + +```yaml +facebook: + app_id: # A Facebook app ID + publisher: # A Facebook page URL or ID of the publishing entity +``` + +While not part a part of Open Graph, you can also add your Facebook username for use in the sidebar and footer. + +```yaml +facebook: + username: "michaelrose" # https://www.facebook.com/michaelrose +``` + +**ProTip:** To debug Open Graph data use [this tool](https://developers.facebook.com/tools/debug/og/object?q=https%3A%2F%2Fmademistakes.com) to test your pages. If content changes aren't reflected you will probably have to hit the **Fetch new scrape information** button to refresh. +{: .notice--info} + +##### Open Graph default image + +For pages that don't have a `header.image` assigned in their YAML Front Matter, `site.og_image` will be used as a fallback. Use your logo, icon, avatar or something else that is meaningful. Just make sure it is place in the `/assets/images/` folder, a minimum size of 120px by 120px, and less than 1MB in file size. + +```yaml +og_image: /assets/images/site-logo.png +``` + +<figure> + <img src="{{ '/assets/images/mm-twitter-card-summary-image.jpg' | relative_url }}" alt="Twitter Card summary example"> + <figcaption>Example of a image placed in a Summary Card.</figcaption> +</figure> + +Documents who have a `header.image` assigned in their YAML Front Matter will appear like this when shared on Twitter and Facebook. + +<figure> + <img src="{{ '/assets/images/mm-twitter-card-summary-large.jpg' | relative_url }}" alt="page shared on Twitter"> + <figcaption>Shared page on Twitter with header image assigned.</figcaption> +</figure> + +<figure> + <img src="{{ '/assets/images/facebook-share-example.jpg' | relative_url }}" alt="page shared on Facebook"> + <figcaption>Shared page on Facebook with header image assigned.</figcaption> +</figure> + +##### Include your social profile in search results + +Use markup on your official website to add your [social profile information](https://developers.google.com/structured-data/customize/social-profiles#adding_structured_markup_to_your_site) to the Google Knowledge panel in some searches. Knowledge panels can prominently display your social profile information. + +```yaml +social: + type: # Person or Organization (defaults to Person) + name: # If the user or organization name differs from the site's name + links: + - "https://twitter.com/yourTwitter" + - "https://www.facebook.com/yourFacebook" + - "https://instagram.com/yourProfile" + - "https://www.linkedin.com/in/yourprofile" +``` + +#### Analytics + +Analytics is disabled by default. To enable globally select one of the following: + +| Name | Analytics Provider | +| -------------------- | --------------------------------------------------------------- | +| **google** | [Google Standard Analytics](https://www.google.com/analytics/) | +| **google-universal** | [Google Universal Analytics](https://www.google.com/analytics/) | +| **google-gtag** | [Google Analytics Global Site Tag](https://www.google.com/analytics/) | +| **custom** | Other analytics providers | + +For Google Analytics add your Tracking Code: + +```yaml +analytics: + provider: "google-gtag" + google: + tracking_id: "UA-1234567-8" + anonymize_ip: false # default +``` + +To use another provider not included with the theme set `provider: "custom"` then add their embed code to `_includes/analytics-providers/custom.html`. + +**Note:** Analytics are disabled by default in `development`. To enable when testing/building locally be sure to set +`JEKYLL_ENV=production` to [force the environment](http://jekyllrb.com/docs/configuration/#specifying-a-jekyll-environment-at-build-time) to production. +{: .notice--info} + +## Site author + +Used as the defaults for defining what appears in the author sidebar. + +![author sidebar example]({{ "/assets/images/mm-author-sidebar-example.jpg" | relative_url }}) + +**Note:** For sites with multiple authors these values can be overridden post by post with custom YAML Front Matter and a data file. For more information on how that works see below. +{: .notice--info} + +```yaml +author: + name : "Your Name" + avatar : "/assets/images/bio-photo.jpg" + bio : "My awesome biography constrained to a sentence or two goes here." + location : "Somewhere, USA" +``` + +Author links are all optional, include the ones you want visible under the `author.links` array. + +| Name | Description | +| --- | --- | +| **label** | Link label (e.g. `"Twitter"`) | +| **icon** | [Font Awesome icon](https://fontawesome.com/icons?d=gallery) classes (e.g. `"fab fa-fw fa-twitter-square"`) | +| **url** | Link URL (e.g. `"https://twitter.com/mmistakes"`) | + +```yaml +author: + name: "Your Name" + avatar: "/assets/images/bio-photo.jpg" + bio: "I am an **amazing** person." # Note: Markdown is allowed + location: "Somewhere" + links: + - label: "Made Mistakes" + icon: "fas fa-fw fa-link" + url: "https://mademistakes.com" + - label: "Twitter" + icon: "fab fa-fw fa-twitter-square" + url: "https://twitter.com/mmistakes" + - label: "GitHub" + icon: "fab fa-fw fa-github" + url: "https://github.com/mmistakes" + - label: "Instagram" + icon: "fab fa-fw fa-instagram" + url: "https://instagram.com/mmistakes" +``` + +To customize the author sidebar, read the full [layout documentation]({{ "/docs/layouts/#author-profile" | relative_url }}). + +## Site footer + +Footer links can be added under the `footer.links` array. + +| Name | Description | +| --- | --- | +| **label** | Link label (e.g. `"Twitter"`) | +| **icon** | [Font Awesome icon](https://fontawesome.com/icons?d=gallery) classes (e.g. `"fab fa-fw fa-twitter-square"`) | +| **url** | Link URL (e.g. `"https://twitter.com/mmistakes"`) | + +```yaml +footer: + links: + - label: "Twitter" + icon: "fab fa-fw fa-twitter-square" + url: "https://twitter.com/mmistakes" + - label: "GitHub" + icon: "fab fa-fw fa-github" + url: "https://github.com/mmistakes" + - label: "Instagram" + icon: "fab fa-fw fa-instagram" + url: "https://instagram.com/mmistakes" +``` + +**Note:** Twitter and Facebook footer links no longer automatically pull from `site.twitter.username` and `site.facebook.username`. This behavior has been deprecated in favor of the `footer.links` array above. +{: .notice--danger} + +To change "Follow:" text that precedes footer links, edit the `follow_label` key in `_data/ui-text.yml`. + +## Reading files + +Nothing out of the ordinary here. `include` and `exclude` may be the only things you need to alter. + +## Conversion and Markdown processing + +Again nothing out of the ordinary here as the theme adheres to the defaults used by GitHub Pages. [**Kramdown**](http://kramdown.gettalong.org/) for Markdown conversion, [**Rouge**](http://rouge.jneen.net/) syntax highlighting, and incremental building disabled. Change them if you need to. + +## Front Matter Defaults + +To save yourself time setting [Front Matter Defaults](https://jekyllrb.com/docs/configuration/front-matter-defaults/) for posts, pages, and collections is the way to go. Sure you can assign layouts and toggle settings like **reading time**, **comments**, and **social sharing** in each file, but that's not ideal. + +Using the `default` key in `_config.yml` you could set the layout and enable author profiles, reading time, comments, social sharing, and related posts for all posts --- in one shot. + +```yaml +defaults: + # _posts + - scope: + path: "" + type: posts + values: + layout: single + author_profile: true + read_time: true + comments: true + share: true + related: true +``` + +Pages Front Matter defaults can be scoped like this: + +```yaml +defaults: + # _pages + - scope: + path: "" + type: pages + values: + layout: single +``` + +And collections like this: + +```yaml +defaults: + # _foo + - scope: + path: "" + type: foo + values: + layout: single +``` + +And of course any default value can be overridden by settings in a post, page, or collection file. All you need to do is specify the settings in the YAML Front Matter. For more examples be sure to check out the demo site's [`_config.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_config.yml). + +## Outputting + +The default permalink style used by the theme is `permalink: /:categories/:title/`. If you have a post named `2016-01-01-my-post.md` with `categories: foo` in the YAML Front Matter, Jekyll will generate `_site/foo/my-post/index.html`. + +**Note:** If you plan on enabling breadcrumb links --- including category names in permalinks is a big part of how those are created. +{: .notice--warning} + +### Paginate + +If [using pagination](https://github.com/jekyll/jekyll-paginate) on the homepage you can change the amount of posts shown with: + +```yaml +paginate: 5 +``` + +You'll also need to include some Liquid and HTML to properly use the paginator, which you can find in the **Layouts** section under [Home Page]({{ "/docs/layouts/#home-page" | relative_url }}). + +The paginator only works on files with name `index.html`. To use pagination in a subfolder --- for example `/recent/`, create `/recent/index.html` and set the `paginate_path` in `_config.yml` to this: + +```yaml +paginate_path: /recent/page:num/ +``` + +**Please note:** When using Jekyll's default [pagination plugin](https://jekyllrb.com/docs/pagination/) `paginator.posts` can only be called once. If you're looking for something more powerful that can paginate category, tag, and collection pages I suggest [**jekyll-paginate-v2**](https://github.com/sverrirs/jekyll-paginate-v2). +{: .notice--info} + +### Timezone + +This sets the timezone environment variable, which Ruby uses to handle time and date creation and manipulation. Any entry from the [IANA Time Zone Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) is valid. The default is the local time zone, as set by your operating system. + +```yaml +timezone: America/New_York +``` + +## Plugins + +When hosting with GitHub Pages a small [set of gems](https://pages.github.com/versions/) have been whitelisted for use. The theme uses a few of them which can be found under `gems`. Additional settings and configurations are documented in the links below. + +| Plugin | Description | +| --- | --- | +| [jekyll-paginate][jekyll-paginate] | Pagination Generator for Jekyll. | +| [jekyll-sitemap][jekyll-sitemap] | Jekyll plugin to silently generate a sitemaps.org compliant sitemap for your Jekyll site. | +| [jekyll-gist][jekyll-gist] | Liquid tag for displaying GitHub Gists in Jekyll sites. | +| [jekyll-feed][jekyll-feed] | A Jekyll plugin to generate an Atom (RSS-like) feed of your Jekyll posts. | +| [jekyll-include-cache][jekyll-include-cache] | Liquid tag that caches Liquid includes. | + +[jekyll-paginate]: https://github.com/jekyll/jekyll-paginate +[jekyll-sitemap]: https://github.com/jekyll/jekyll-sitemap +[jekyll-gist]: https://github.com/jekyll/jekyll-gist +[jekyll-feed]: https://github.com/jekyll/jekyll-feed +[jekyll-include-cache]: https://github.com/benbalter/jekyll-include-cache + +If you're hosting elsewhere then you don't really have to worry about what is whitelisted as you are free to include whatever [Jekyll plugins](https://jekyllrb.com/docs/plugins/) you desire. + +**Note:** The [jekyll-include-cache](https://github.com/benbalter/jekyll-include-cache) plugin needs to be installed in your `Gemfile` and added to the `plugins` array of `_config.yml`. Otherwise you'll throw `Unknown tag 'include_cached'` errors at build. +{: .notice--warning} + +## Archive settings + +The theme ships with support for taxonomy (category and tag) pages. GitHub Pages hosted sites need to use a _Liquid only_ approach while those hosted elsewhere can use plugins like [**jekyll-archives**][jekyll-archives] to generate these pages automatically. + +[jekyll-archives]: https://github.com/jekyll/jekyll-archives + +The default `type` is set to use Liquid. + +**Note:** `category_archive` and `tag_archive` were previously named `categories` and `tags`. Names were changed to avoid possible conflicts with `site.categories` and `site.tags`. +{: .notice--danger} + +```yaml +category_archive: + type: liquid + path: /categories/ +tag_archive: + type: liquid + path: /tags/ +``` + +Which would create category and tag links in the breadcrumbs and page meta like: `/categories/#foo` and `/tags/#foo`. + +**Note:** these are simply hash (fragment) links into the full taxonomy index pages. For them to resolve properly, the category and tag index pages need to exist at [`/categories/index.html`](https://github.com/{{ site.repository }}/blob/master/docs/_pages/category-archive.md) (copy to `_pages/category-archive.md`) and [`/tags/index.html`](https://github.com/{{ site.repository }}/blob/master/docs/_pages/tag-archive.md) (copy to `_pages/tag-archive.md`). +{: .notice--warning} + +If you have the luxury of using Jekyll Plugins, then [**jekyll-archives**][jekyll-archives] will create a better experience as discrete taxonomy pages would be generated, and their corresponding links would be "real" (not just hash/fragment links into a larger index). However, the plugin will not generate the taxonomy index pages (`category-archive.md` and `tag-archive.md`) so you'd still need to manually create them if you'd like to have them (see note above). + +First, you'll need to make sure that the `jekyll-archives` plugin is installed. Either run `gem install jekyll-archives` or add the following to your `Gemfile`: + +``` +group :jekyll_plugins do + gem "jekyll-archives" +end +``` + +Then run `bundle install`. + +Now that the plugin is installed, change `type` to `jekyll-archives` and apply the following [configurations](https://github.com/jekyll/jekyll-archives/blob/master/docs/configuration.md): + +```yaml +category_archive: + type: jekyll-archives + path: /categories/ +tag_archive: + type: jekyll-archives + path: /tags/ +jekyll-archives: + enabled: + - categories + - tags + layouts: + category: archive-taxonomy + tag: archive-taxonomy + permalinks: + category: /categories/:name/ + tag: /tags/:name/ +``` + +**Note:** The `archive-taxonomy` layout used by jekyll-archives is provided with the theme and can be found in the `_layouts` folder. +{: .notice--info} + +<div class="notice--success" markdown="1"> + +<h4 class="no_toc"><i class="fas fa-lightbulb"></i> Tip</h4> + +To apply [Front Matter defaults](https://jekyllrb.com/docs/configuration/front-matter-defaults/) to pages generated by the `jekyll-archives` plugin, you can specify a scope of an empty `path` and a `type` of either `tag` or `category`. + +For example, the following configuration enables author profile on tag archives and disables comments on category archives. + +```yaml +defaults: + - scope: + path: "" + type: tag + values: + author_profile: true + - scope: + path: "" + type: category + values: + comments: false +``` + +</div> + +## HTML compression + +If you care at all about performance (and really who doesn't) compressing the HTML files generated by Jekyll is a good thing to do. + +If you're hosting with GitHub Pages there aren't many options afforded to you for optimizing the HTML Jekyll generates. Thankfully there is some Liquid wizardry you can use to strip whitespace and comments to reduce file size. + +There's a variety of configurations and caveats to using the `compress` layout, so be sure to read through the [documentation](http://jch.penibelst.de/) if you decide to make change the defaults set in the theme's `_config.yml`. + +```yaml +compress_html: + clippings: all + ignore: + envs: development # disable compression in dev environment +``` + +**Caution:** Inline JavaScript comments can cause problems with `compress.html`, so be sure to `/* comment this way */` and avoid `// these sorts of comments`. +{: .notice--warning} + +**Note:** CDN services such as CloudFlare provide optional automatic minification for HTML, CSS, and JavaScript. If you are serving your site via such a service and have minification enabled, this configuration might be redundant. +{: .notice--info} diff --git a/docs/06-faq.md b/docs/06-faq.md new file mode 100644 index 00000000..d8f5bc40 --- /dev/null +++ b/docs/06-faq.md @@ -0,0 +1,17 @@ + +#### Q: HASP Settings + +A: + +#### Q: Is there a file browser built-in? + +*A:* There is no native file browser included yet, as this currently is low on the priority list. + +However, you can upload the `edit.htm.gz` (3kB) file to the SPIFFS partition from the ESP32 FSBrowser repository. +Download it from: https://github.com/espressif/arduino-esp32/blob/master/libraries/WebServer/examples/FSBrowser/data/edit.htm.gz + +When the `edit.htm.gz` file is present on Spiffs you will see an additional File Browser button on the Main Webpage: +![HTTP configuration](assets/images/hasp/faq_file_browser.png "File Browser") + +Using that webpage, you can right-click and delete files: +![HTTP configuration](assets/images/hasp/faq_file_delete.png "Delete file") diff --git a/docs/06-overriding-theme-defaults.md b/docs/06-overriding-theme-defaults.md new file mode 100644 index 00000000..f0fa82b2 --- /dev/null +++ b/docs/06-overriding-theme-defaults.md @@ -0,0 +1,20 @@ +When installing the theme as a Ruby Gem its layouts, includes, stylesheets, and other assets are all bundled in the `gem`. Meaning they're not easily visible in your project. + +Each of these files can be modified, but you'll need to copy the default version into your project first. For example, if you wanted to modify the default [`single` layout](https://github.com/mmistakes/minimal-mistakes/blob/master/_layouts/single.html), you'd start by copying it to `_layouts/single.html`. + +**ProTip**: To locate theme files, run `bundle info minimal-mistakes-jekyll`. Then copy the files you want to override from the returned path, to the appropriate folder in your project. +{: .notice--info} + +Jekyll will use the files in your project first before falling back to the default versions of the theme. It exhibits this behavior with files in the following folders: + +``` +/assets +/_layouts +/_includes +/_sass +``` + +Additionally, from `v4.5.0` the theme-gem will also exhibit above behavior for `/_data` via a plugin. +Consequently, the data files for UI Text and Navigation are also bundled within the theme-gem. + +For more information on customizing the theme's [stylesheets]({{ "/docs/stylesheets/" | relative_url }}) and [JavaScript]({{ "/docs/javascript/" | relative_url }}), see the appropriate pages. diff --git a/docs/07-navigation.md b/docs/07-navigation.md new file mode 100644 index 00000000..8a636266 --- /dev/null +++ b/docs/07-navigation.md @@ -0,0 +1,65 @@ +Customize site navigational links through a Jekyll data file. + +## Masthead + +The masthead links use a "priority plus" design pattern. Meaning, show as many navigation items that will fit horizontally with a toggle to reveal the rest. + +To define these links add titles and URLs under the `main` key in `_data/navigation.yml`: + +```yaml +main: + - title: "Quick-Start Guide" + url: /projects/hasp-lvgl/quick-start-guide/ + - title: "Posts" + url: /year-archive/ + - title: "Categories" + url: /categories/ + - title: "Tags" + url: /tags/ + - title: "Pages" + url: /page-archive/ + - title: "Collections" + url: /collection-archive/ + - title: "External Link" + url: https://google.com +``` + +Which will give you a responsive masthead similar to this: + +![priority plus masthead animation]({{ "/assets/images/mm-priority-plus-masthead.gif" | relative_url }}) + +Optionally, you can add a `description` key per title in the `main` key. This `description` will show up like a tooltip, when the user hovers over the link on a desktop browser. + +**ProTip:** Put the most important links first so they're always visible and not hidden behind the **menu toggle**. +{: .notice--info} + +## Breadcrumbs (beta) + +Enable breadcrumb links to help visitors better navigate deep sites. Because of the fragile method of implementing them they don't always produce accurate links reliably. For best results: + +1. Use a category based permalink structure e.g. `permalink: /:categories/:title/` +2. Manually create pages for each category or use a plugin like [jekyll-archives](https://github.com/jekyll/jekyll-archives) to auto-generate them. If these pages don't exist breadcrumb links to them will be broken. + +![breadcrumb navigation example]({{ "/assets/images/mm-breadcrumbs-example.jpg" | relative_url }}) + +```yaml +breadcrumbs: true # disabled by default +``` + +Breadcrumb start link text and separator character can both be changed in `_data/ui-text.yml`. + +```yaml +breadcrumb_home_label : "Home" +breadcrumb_separator : "/" +``` + +For breadcrumbs that resemble something like `Start > Blog > My Awesome Post` you'd apply these settings: + +```yaml +breadcrumb_home_label : "Start" +breadcrumb_separator : ">" +``` + +## Custom sidebar navigation menu + +See the [**sidebars** documentation]({{ "/projects/hasp-lvgl/layouts/#custom-sidebar-navigation-menu" | relative_url }}) for information on setting up a custom navigation menu. \ No newline at end of file diff --git a/docs/08-ui-text.md b/docs/08-ui-text.md new file mode 100644 index 00000000..46927d31 --- /dev/null +++ b/docs/08-ui-text.md @@ -0,0 +1,43 @@ +Text for UI elements, `_layouts`, and `_includes` grouped together as a set of translation keys. This is by no means a full-on i18n solution, but it does help make customizing theme text a bit easier. + +The English[^yaml-anchors] main keys in [`_data/ui-text.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_data/ui-text.yml) are translated in the following languages: + +- Brazilian Portuguese (Português brasileiro) +- Catalan +- Chinese +- Danish +- Dutch +- Finnish +- French (Français) +- German (Deutsch) +- Greek +- Hungarian +- Indonesian +- Irish (Gaeilge) +- Italian (Italiano) +- Korean +- Japanese +- Malayalam +- Myanmar (Burmese) +- Nepali (Nepalese) +- Polish +- Persian (فارسی) +- Romanian +- Russian +- Slovak +- Spanish (Español) +- Swedish +- Thai +- Turkish (Türkçe) +- Vietnamese + +If you're are interested in localizing them into other languages feel free to submit a pull request and I will be happy to look it over. + +[^yaml-anchors]: `en-US`, and `en-GB` use [YAML anchors](http://www.yaml.org/spec/1.2/spec.html#id2785586) to reference the values in `en` as to not repeat them. + +Many of the label based keys like `meta_label`, `categories_label`, `tags_label`, `share_on_label`, and `follow_label` can be left blank if you'd like to omit them from view. It really depends on you and if you want an even more minimal look to your site. + +![UI text labels]({{ "/assets/images/mm-ui-text-labels.jpg" | relative_url }}) + +**Note:** The theme comes with localized text in English (`en`, `en-US`, `en-GB`). If you change `locale` in `_config.yml` to something else, most of the UI text will go blank. Be sure to add the corresponding locale key and translated text to `_data/ui-text.yml` to avoid this. +{: .notice--warning} diff --git a/docs/09-authors.md b/docs/09-authors.md new file mode 100644 index 00000000..4b691232 --- /dev/null +++ b/docs/09-authors.md @@ -0,0 +1,44 @@ +Sites that may have content authored from various individuals can be accommodated by using [data files](https://jekyllrb.com/docs/datafiles/). + +To assign an author to a post or page that is different from the site author specified in `_config.yml`: + +**Step 1.** Create `_data/authors.yml` and add authors using the following format. Any variables found under `author:` in `_config.yml` can be used (e.g. `name`, `bio`, `avatar`, author `links`, etc.). + +```yaml +# /_data/authors.yml + +Billy Rick: + name : "Billy Rick" + bio : "What do you want, jewels? I am a very extravagant man." + avatar : "/assets/images/bio-photo-2.jpg" + links: + - label: "Email" + icon: "fas fa-fw fa-envelope-square" + url: "mailto:billyrick@rick.com" + - label: "Website" + icon: "fas fa-fw fa-link" + url: "https://thewhip.com" + - label: "Twitter" + icon: "fab fa-fw fa-twitter-square" + url: "https://twitter.com/extravagantman" + +Cornelius Fiddlebone: + name : "Cornelius Fiddlebone" + bio : "I ordered what?" + avatar : "/assets/images/bio-photo.jpg" + links: + - label: "Email" + icon: "fas fa-fw fa-envelope-square" + url: "mailto:cornelius@thewhip.com" + - label: "Twitter" + icon: "fab fa-fw fa-twitter-square" + url: "https://twitter.com/rhymeswithsackit" +``` + +**Step 2.** Assign one of the authors in `authors.yml` to a post or page you wish to override the `site.author` with. + +Example: To assign `Billy Rick` as an author for a post the following YAML Front Matter would be applied: + +```yaml +author: Billy Rick +``` diff --git a/docs/10-layouts.md b/docs/10-layouts.md new file mode 100644 index 00000000..ebe4538c --- /dev/null +++ b/docs/10-layouts.md @@ -0,0 +1,734 @@ +The bread and butter of any theme. Below you'll find the layouts included with Minimal Mistakes, what they look like and the type of content they've been built for. + +## Default layout + +The base layout all other layouts inherit from. There's not much to this layout apart from pulling in several `_includes`: + +* `<head>` elements +* masthead navigation links +* {% raw %}`{{ content }}`{% endraw %} +* page footer +* scripts + +**Note:** You won't ever assign this layout directly to a post or page. Instead all other layouts will build off of it by setting `layout: default` in their YAML Front Matter. +{: .notice--warning} + +### Layout based and user-defined classes + +Class names corresponding to each layout are automatically added to the `<body>` element eg. `<body class="layout--single">`. + +| layout | class name | +| ---------------- | --------------------------- | +| archive | `.layout--archive` | +| archive-taxonomy | `.layout--archive-taxonomy` | +| search | `.layout--search` | +| single | `.layout--single` | +| splash | `.layout--splash` | +| home | `.layout--home` | +| posts | `.layout--posts` | +| categories | `.layout--categories` | +| category | `.layout--category` | +| tags | `.layout--tags` | +| tag | `.layout--tag` | + +Using YAML Front Matter you can also assign custom classes to target with CSS or JavaScript. Perfect for "art directed" posts or adding custom styles to specific pages. + +Example: + +```yaml +--- +layout: splash +classes: + - landing + - dark-theme +--- +``` + +Outputs: + +```html +<body class="layout--splash landing dark-theme"> +``` + +### Canonical URL + +You can set custom Canonical URL for a page by specifying `canonical_url` option in pages YAML Front Matter. For example, if you have the following: + +```yaml +layout: single +title: Title of Your Post +canonical_url: "https://yoursite.com/custom-canonical-url" +``` + +This will generate the following in the `<head>` of your page: + +```html +<link rel="canonical" href="https://yoursite.com/custom-canonical-url" /> +``` + +## Compress layout + +A Jekyll layout that compresses HTML in pure Liquid. To enable add `layout: compress` to `_layouts/default.html`. + +**Note:** Has been known to mangle markup and break JavaScript... especially if inline `// comments` are present. For this reason it has been disabled by default. +{: .notice--danger} + +* [Documentation](http://jch.penibelst.de/) + +## Single layout + +The layout you'll likely use the most --- sidebar and main content combo. + +**Includes:** + +* Optional header image with caption +* Optional header overlay (solid color/image) + text and optional "call to action" button +* Optional social sharing links module +* Optional comments module +* Optional related posts module +* Wide page variant + +{% include gallery id="single_layout_gallery" caption="Image header and meta info examples for `single` layout" %} + +Assign with `layout: single` , or better yet apply as a [Front Matter default]({{ "/docs/configuration/#front-matter-defaults" | relative_url }}) in `_config.yml`. + +### Wide page + +To expand the main content to the right, filling the space of what is normally occupied by the table of contents. Add the following to a post or page's YAML Front Matter: + +```yaml +classes: wide +``` + +**Note:** If the page contains a table of contents, it will no longer appear to the right. Instead it will be forced into the main content container directly following the page's title. +{: .notice--info} + +### Table of contents + +Auto-generated table of contents list for your posts and pages can be enabled by adding `toc: true` to the YAML Front Matter. + +![table of contents example]({{ "/assets/images/mm-toc-helper-example.jpg" | relative_url }}) + +| Parameter | Required | Description | Default | +| --------- | -------- | ----------- | ------- | +| **toc** | Optional | Show table of contents. (boolean) | `false` | +| **toc_label** | Optional | Table of contents title. (string) | `toc_label` in UI Text data file. | +| **toc_icon** | Optional | Table of contents icon, displays before the title. (string) | [Font Awesome](https://fontawesome.com/icons?d=gallery&s=solid&m=free) <i class="fas fa-file-alt"></i> **file-alt** icon. Other FA icons can be used instead. | + +**TOC example with custom title and icon** + +```yaml +--- +toc: true +toc_label: "My Table of Contents" +toc_icon: "cog" +--- +``` + +## Archive layout + +Essentially the same as `single` with markup adjustments and some modules removed. + +**Includes:** + +* Optional header image with caption +* Optional header overlay (solid color/image) + text and optional "call to action" button +* List and grid views + +<figure> + <img src="{{ '/assets/images/mm-layout-archive.png' | relative_url }}" alt="archive layout example"> + <figcaption>List view example.</figcaption> +</figure> + +Below are sample archive pages you can easily drop into your project, taking care to rename `permalink`, `title`, or the filename to fit your site. Each is 100% compatible with GitHub Pages. + +* [All Posts Grouped by Category -- List View][posts-categories] +* [All Posts Grouped by Tag -- List View][posts-tags] +* [All Posts Grouped by Year -- List View][posts-year] +* [All Posts Grouped by Collection -- List View][posts-collection] +* [Portfolio Collection -- Grid View][portfolio-collection] + +[posts-categories]: https://github.com/{{ site.repository }}/blob/master/docs/_pages/category-archive.md +[posts-tags]: https://github.com/{{ site.repository }}/blob/master/docs/_pages/tag-archive.md +[posts-year]: https://github.com/{{ site.repository }}/blob/master/docs/_pages/year-archive.md +[posts-collection]: https://github.com/{{ site.repository }}/blob/master/docs/_pages/collection-archive.html +[portfolio-collection]: https://github.com/{{ site.repository }}/blob/master/docs/_pages/portfolio-archive.md + +Post and page excerpts are auto-generated by Jekyll which grabs the first paragraph of text. To override this text with something more specific use the following YAML Front Matter: + +```yaml +excerpt: "A unique line of text to describe this post that will display in an archive listing and meta description with SEO benefits." +``` + +### Wide page + +To expand the main content to the right, filling the space of what is normally occupied by the table of contents. Add the following to a post or page's YAML Front Matter: + +```yaml +classes: wide +``` + +### Grid view + +Adding `type=grid` to the `archive-single` helper will display archive posts in a 4 column grid. For example to create an archive displaying all documents in the portfolio collection: + +Create a portfolio archive page (eg. `_pages/portfolio-archive.md`) with the following YAML Front Matter: + +```yaml +--- +title: Portfolio +layout: collection +permalink: /portfolio/ +collection: portfolio +entries_layout: grid +--- +``` + +Teaser images are assigned similar to header images using the following YAML Front Matter: + +```yaml +header: + teaser: path-to-teaser-image.jpg +``` + +**Note:** More information on using this `_include` can be found under [**Helpers**]({{ "/docs/helpers/" | relative_url }}). +{: .notice--info} + +## Taxonomy archives + +If you have the luxury of using Jekyll plugins, the creation of category and tag archives is greatly simplified. Simply enable support for the [`jekyll-archives`](https://github.com/jekyll/jekyll-archives) plugin with a few `_config.yml` settings as noted in the [**Configuration**]({{ "/docs/configuration/#archive-settings" | relative_url }}) section and you're good to go. + +![archive taxonomy layout example]({{ "/assets/images/mm-layout-archive-taxonomy.png" | relative_url }}) + +If you're not using the `jekyll-archives` plugin then you need to create archive pages yourself. Sample taxonomy archives can be found by grabbing the Markdown sources below and adding to your site. + +| Name | Layout | Example | +| -------------------- | ------ | ------ | +| [Posts Archive](https://mmistakes.github.io/minimal-mistakes/year-archive/) | `layout: posts` | [year-archive.md](https://github.com/mmistakes/minimal-mistakes/blob/master/docs/_pages/year-archive.md) | +| [Categories Archive](https://mmistakes.github.io/minimal-mistakes/categories/) | `layout: categories` | [category-archive.md](https://github.com/mmistakes/minimal-mistakes/blob/master/docs/_pages/category-archive.md) | +| [Category Archive](https://mmistakes.github.io/minimal-mistakes/categories/edge-case/) | `layout: category` | [edge-case.md](https://github.com/mmistakes/minimal-mistakes/blob/master/docs/_pages/edge-case.md) | +| [Tags Archive](https://mmistakes.github.io/minimal-mistakes/tags/) | `layout: tags` | [tag-archive.md](https://github.com/mmistakes/minimal-mistakes/blob/master/docs/_pages/tag-archive.md) | +| [Tag Archive](https://mmistakes.github.io/minimal-mistakes/tags/markup/) | `layout: tag` | [markup.md](https://github.com/mmistakes/minimal-mistakes/blob/master/docs/_pages/markup.md) | +| [Collection Archive](https://mmistakes.github.io/minimal-mistakes/recipes-archive/) | `layout: collection` | [recipes-archive.md](https://github.com/mmistakes/minimal-mistakes/blob/master/docs/_pages/recipes-archive.md) | + +**Note:** By default, documents are shown in a list view. To change to a grid view add `entries_layout: grid` to the page's front matter. +{: .notice--info} + +### `layout: posts` + +This layout displays all posts grouped by the year they were published. It accommodates the same front matter as `layout: archive`. + +### `layout: categories` + +This layout displays all posts grouped category. It accommodates the same front matter as `layout: archive`. + +### `layout: tags` + +This layout displays all posts grouped by tag. It accommodates the same front matter as `layout: archive`. + +### `layout: collection` + +This layout displays all documents grouped by a specific collection. It accommodates the same front matter as `layout: archive` with the addition of the following: + +```yaml +collection: # collection name +entries_layout: # list (default), grid +show_excerpts: # true (default), false +sort_by: # date (default) title +sort_order: # forward (default), reverse +``` + +To create a page showing all documents in the `recipes` collection you'd create `recipes.md` in the root of your project and add this front matter: + +```yaml +title: Recipes +layout: collection +permalink: /recipes/ +collection: recipes +``` + +If you want to sort the collection by title add `sort_by: title`. If you want reverse sorting, add `sort_order: reverse`. + +### `layout: category` + +This layout displays all posts grouped by a specific category. It accommodates the same front matter as `layout: archive` with the addition of the following: + +```yaml +taxonomy: # category name +entries_layout: # list (default), grid +``` + +To create a page showing all posts assigned to the category `foo` you'd create `foo.md` and add this front matter: + +```yaml +title: Foo +layout: category +permalink: /categories/foo/ +taxonomy: foo +``` + +### `layout: tag` + +This layout displays all posts grouped by a specific tag. It accommodates the same front matter as `layout: archive` with the addition of the following: + +```yaml +taxonomy: # tag name +entries_layout: # list (default), grid +``` + +To create a page showing all posts assigned to the tag `foo bar` you'd create `foo-bar.md` and add this front matter: + +```yaml +title: Foo Bar +layout: tag +permalink: /tags/foo-bar/ +taxonomy: foo bar +``` + +## Home page layout + +A derivative archive page layout to be used as a simple home page. It is built to show a paginated list of recent posts based off of the [pagination settings]({{ "/docs/configuration/#paginate" | relative_url }}) in `_config.yml`. + +<figure> + <img src="{{ '/assets/images/mm-home-post-pagination-example.jpg' | relative_url }}" alt="paginated home page example"> + <figcaption>Example of a paginated home page showing 5 recent posts.</figcaption> +</figure> + +To use create `index.html` at the root of your project and add the following YAML Front Matter: + +```yaml +--- +layout: home +--- +``` + +Then configure pagination in `_config.yml`. + +```yaml +paginate: 5 # amount of posts to show +paginate_path: /page:num/ +``` + +If you'd rather have a paginated page of posts reside in a subfolder instead of acting as your homepage make the following adjustments. + +Create `index.html` in the location you'd like. For example if I wanted it to live at **/blog** I'd create `/blog/index.html` with `layout: home` in its YAML Front Matter. + +Then adjust the `paginate_path` in **_config.yml** to match. + +```yaml +paginate_path: /blog/page:num +``` + +**Note:** Jekyll can only paginate a single `index.html` file. If you'd like to paginate more pages (e.g. category indexes) you'll need the help of a custom plugin. For more pagination related settings check the [**Configuration**]({{ "/docs/configuration/#paginate" | relative_url }}) section. +{: .notice--info} + +## Splash page layout + +For full-width landing pages that need a little something extra add `layout: splash` to the YAML Front Matter. + +**Includes:** + +* Optional header image with caption +* Optional header overlay (solid color/image) + text and optional "call to action" button +* Feature blocks (`left`, `center`, and `right` alignment options) + +![splash page layout example]({{ "/assets/images/mm-layout-splash.png" | relative_url }}) + +Feature blocks can be assigned and aligned to the `left`, `right`, or `center` with a sprinkling of YAML. For full details on how to use the `feature_row` helper check the [**Content**]({{ "/docs/helpers/" | relative_url }}) section or review a [sample splash page](https://github.com/{{ site.repository }}/blob/master/docs/_pages/splash-page.md). + +## Search page layout + +A page with a search form. Add `layout: search` to the YAML Front Matter similar to [this example](https://github.com/mmistakes/minimal-mistakes/blob/master/test/_pages/search.md) on the test site. + +![search page layout example]({{ "/assets/images/search-layout-example.png" | relative_url }}) + +**Note:** A page using the `layout: search` isn't compatible with the new [site search feature]({{ "/docs/configuration/#site-search" | relative_url }}) incorporated in the masthead. +{: .notice--warning} + +### Exclusions + +If you would like to exclude specific pages/posts from the search index set the search flag to `false` in the YAML Front Matter for the page/post. + +```yaml +search: false +``` + +**ProTip:** Add a link to this page in the masthead navigation. +{: .notice--info} + +--- + +## Headers + +To add some visual punch to a post or page, a large full-width header image can be included. + +Be sure to resize your header images. `~1280px` is a good width if you aren't [responsively serving up images](http://alistapart.com/article/responsive-images-in-practice). Through the magic of CSS they will scale up or down to fill the container. If you go with something too small it will look like garbage when upscaled, and something too large will hurt performance. + +**Please Note:** Paths for image headers, overlays, teasers, [galleries]({{ "/docs/helpers/#gallery" | relative_url }}), and [feature rows]({{ "/docs/helpers/#feature-row" | relative_url }}) have changed and require a full path. Instead of just `image: filename.jpg` you'll need to use the full path eg: `image: /assets/images/filename.jpg`. The preferred location is now `/assets/images/`, but can be placed elsewhere or external hosted. This all applies for image references in `_config.yml` and `author.yml` as well. +{: .notice--danger} + +![single layout header image example]({{ "/assets/images/mm-single-header-example.jpg" | relative_url }}) + +Place your images in the `/assets/images/` folder and add the following YAML Front Matter: + +```yaml +header: + image: /assets/images/image-filename.jpg +``` + +For externally hosted images include the full image path instead of just the filename: + +```yaml +header: + image: http://some-site.com/assets/images/image.jpg +``` + +To provide a custom alt tag for screen readers: + +```yaml +header: + image: /assets/images/unsplash-image-1.jpg + image_description: "A description of the image" +``` + +To include a caption or attribution for the image: + +```yaml +header: + image: /assets/images/unsplash-image-1.jpg + caption: "Photo credit: [**Unsplash**](https://unsplash.com)" +``` + +**ProTip:** Captions written in Markdown are supported, so feel free to add links, or style text. Just be sure to wrap it in quotes. +{: .notice--info} + +### Header overlay + +To overlay text on top of a header image you have a few more options: + +| Name | Description | Default | +| ---- | ----------- | ------- | +| **overlay_image** | Header image you'd like to overlay. Same rules as `header.image` from above. | | +| **overlay_filter** | Color/opacity to overlay on top of the header image eg: `0.5` or `rgba(255, 0, 0, 0.5)`. | +| **show_overlay_excerpt** | Display excerpt in the overlay text | true | +| **excerpt** | Auto-generated page excerpt is added to the overlay text or can be overridden. | | +| **tagline** | Overrides page excerpt. Useful when header text needs to be different from excerpt in archive views. | | +| **actions** | Call to action button links (`actions` array: `label` and `url`). More than one button link can be assigned. | | +| **cta_label** | Deprecated, use `actions` instead. Call to action button text label. | `more_label` in UI Text data file | +| **cta_url** | Deprecated, use `actions` instead. Call to action button URL. | | + +With this YAML Front Matter: + +```yaml +excerpt: "This post should display a **header with an overlay image**, if the theme supports it." +header: + overlay_image: /assets/images/unsplash-image-1.jpg + caption: "Photo credit: [**Unsplash**](https://unsplash.com)" + actions: + - label: "More Info" + url: "https://unsplash.com" +``` + +You'd get a header image overlaid with text and a call to action button like this: + +![single layout header overlay example]({{ "/assets/images/mm-single-header-overlay-example.jpg" | relative_url }}) + +You also have the option of specifying a solid background-color to use instead of an image. + +![single layout header overlay with background fill]({{ "/assets/images/mm-single-header-overlay-fill-example.jpg" | relative_url }}) + +```yaml +excerpt: "This post should display a **header with a solid background color**, if the theme supports it." +header: + overlay_color: "#333" +``` + +You can also specifying the opacity (between `0` and `1`) of a black overlay like so: + +![transparent black overlay]({{ "/assets/images/mm-header-overlay-black-filter.jpg" | relative_url }}) + +```yaml +excerpt: "This post should [...]" +header: + overlay_image: /assets/images/unsplash-image-1.jpg + overlay_filter: 0.5 # same as adding an opacity of 0.5 to a black background + caption: "Photo credit: [**Unsplash**](https://unsplash.com)" + actions: + - label: "Download" + url: "https://github.com" +``` + +Or if you want to do more fancy things, go full rgba: + +![transparent red overlay]({{ "/assets/images/mm-header-overlay-red-filter.jpg" | relative_url }}) + +```yaml +excerpt: "This post should [...]" +header: + overlay_image: /assets/images/unsplash-image-1.jpg + overlay_filter: rgba(255, 0, 0, 0.5) + caption: "Photo credit: [**Unsplash**](https://unsplash.com)" + actions: + - label: "Download" + url: "https://github.com" +``` + +Multiple call to action button links can be assigned like this: + +```yaml +excerpt: "This post should display a **header with an overlay image**, if the theme supports it." +header: + overlay_image: /assets/images/unsplash-image-1.jpg + caption: "Photo credit: [**Unsplash**](https://unsplash.com)" + actions: + - label: "Foo Button" + url: "#foo" + - label: "Bar Button" + url: "#bar" +``` + +### Open Graph & Twitter Card images + +By default the large page header or overlay images are used for sharing previews. If you'd like to set this image to something else use `page.header.og_image` like: + +```yaml +header: + image: /assets/images/your-page-image.jpg + og_image: /assets/images/your-og-image.jpg +``` + +**ProTip:** `og_image` is useful for setting OpenGraph images on pages that don't have a header or overlay image. +{: .notice--info} + +--- + +## Sidebars + +The space to the left of a page's main content is blank by default, but has the ability to show an author profile (name, short biography, social media links), custom content, or both. + +### Author profile + +Add `author_profile: true` to a post or page's YAML Front Matter. + +![single layout example]({{ "/assets/images/mm-layout-single.png" | relative_url }}) + +Better yet, enable it with Front Matter Defaults set in `_config.yml`. + +```yaml +defaults: + # _posts + - scope: + path: "" + type: posts + values: + author_profile: true +``` + +**Note:** To disable the author sidebar profile for a specific post or page, add `author_profile: false` to the YAML Front Matter instead. +{: .notice--warning} + +To assign more author links, add to the `author.links` array in [`_config.yml`]({{ "/docs/configuration/" | relative_url }}) link so. Any of [Font Awesome's icons](https://fontawesome.com/icons?d=gallery) are available for use. + +```yaml +author: + name: "Your Name" + avatar: "/assets/images/bio-photo.jpg" + bio: "I am an **amazing** person." # Note: Markdown is allowed + location: "Somewhere" + links: + - label: "Made Mistakes" + icon: "fas fa-fw fa-link" + url: "https://mademistakes.com" + - label: "Twitter" + icon: "fab fa-fw fa-twitter-square" + url: "https://twitter.com/mmistakes" + - label: "GitHub" + icon: "fab fa-fw fa-github" + url: "https://github.com/mmistakes" + - label: "Instagram" + icon: "fab fa-fw fa-instagram" + url: "https://instagram.com/mmistakes" +``` + +**Note:** Depending on the icon and theme skin used, colors may not be used. Popular social networks like Twitter, Facebook, Instagram, etc. have the appropriate brand color set in CSS. To change or add missing colors edit [`_utilities.scss`](https://github.com/mmistakes/minimal-mistakes/blob/master/_sass/minimal-mistakes/_utilities.scss) in `<site root>/_sass/minimal-mistakes/`. +{: .notice--info} + +For example, to color a Reddit icon, simply add a `color` declaration and the corresponding hex code like so: + +```scss +.social-icons { + .fa-reddit { + color: #ff4500; + } +} +``` + +![Reddit link in author profile with color]({{ "/assets/images/mm-author-profile-reddit-color.png" | relative_url }}) + +### Custom sidebar content + +Blocks of content can be added by using the following under `sidebar`: + +| Name | Description | +| ---- | ----------- | +| **title** | Title or heading. | +| **image** | Image path placed in `/images/` folder or an external URL. | +| **image_alt** | Alternate description for image. | +| **text** | Text. Markdown is allowed. | + +Multiple blocks can also be added by following the example below: + +```yaml +sidebar: + - title: "Title" + image: http://placehold.it/350x250 + image_alt: "image" + text: "Some text here." + - title: "Another Title" + text: "More text here." +``` + +<figure> + <img src="{{ '/assets/images/mm-custom-sidebar-example.jpg' | relative_url }}" alt="custom sidebar content example"> + <figcaption>Example of custom sidebar content added as YAML Front Matter.</figcaption> +</figure> + +**Note:** Custom sidebar content added to a post or page's YAML Front Matter will appear below the author profile if enabled with `author_profile: true`. +{: .notice--info} + +### Custom sidebar navigation menu + +To create a sidebar menu[^sidebar-menu] similar to the one found in the theme's documentation pages you'll need to modify a `_data` file and some YAML Front Matter. + +[^sidebar-menu]: Sidebar menu supports 1 level of nested links. + +<figure> + <img src="{{ '/assets/images/mm-custom-sidebar-nav.jpg' | relative_url }}" alt="sidebar navigation example"> + <figcaption>Custom sidebar navigation menu example.</figcaption> +</figure> + +To start, add a new key to `_data/navigation.yml`. This will be referenced later in via YAML Front Matter so keep it short and memorable. In the case of the theme's documentation menu I used `docs`. + +**Sample sidebar menu links:** + +```yaml +docs: + - title: Getting Started + children: + - title: "Quick-Start Guide" + url: /docs/quick-start-guide/ + - title: "Structure" + url: /docs/structure/ + - title: "Installation" + url: /docs/installation/ + - title: "Upgrading" + url: /docs/upgrading/ + + - title: Customization + children: + - title: "Configuration" + url: /docs/configuration/ + - title: "Navigation" + url: /docs/navigation/ + - title: "UI Text" + url: /docs/ui-text/ + - title: "Authors" + url: /docs/authors/ + - title: "Layouts" + url: /docs/layouts/ + + - title: Content + children: + - title: "Working with Posts" + url: /docs/posts/ + - title: "Working with Pages" + url: /docs/pages/ + - title: "Working with Collections" + url: /docs/collections/ + - title: "Helpers" + url: /docs/helpers/ + - title: "Utility Classes" + url: /docs/utility-classes/ + + - title: Extras + children: + - title: "Stylesheets" + url: /docs/stylesheets/ + - title: "JavaScript" + url: /docs/javascript/ +``` + +Now you can pull these links into any page by adding the following YAML Front Matter. + +```yaml +sidebar: + nav: "docs" +``` + +**Note:** `nav: "docs"` references the `docs` key in `_data/navigation.yml` so make sure they match. +{: .notice--info} + +If you're adding a sidebar navigation menu to several pages the use of Front Matter Defaults is a better option. You can define them in `_config.yml` to avoid adding it to every page or post. + +**Sample sidebar nav default:** + +```yaml +defaults: + # _docs + - scope: + path: "" + type: docs + values: + sidebar: + nav: "docs" +``` + +--- + +## Social sharing links + +The `single` layout has an option to enable social links at the bottom of posts for sharing on Twitter, Facebook, and LinkedIn. Similar to the links found in the author sidebar, the theme ships with defaults for the most common social networks. + +![default social share link buttons]({{ "/assets/images/mm-social-share-links-default.png" | relative_url }}) + +To enable these links add `share: true` to a post or page's YAML Front Matter or use a [default](https://jekyllrb.com/docs/configuration/#front-matter-defaults) in your `_config.yml` to apply more globally. + +If you'd like to add, remove, or change the order of these default links you can do so by editing [`_includes/social-share.html`](https://github.com/mmistakes/minimal-mistakes/blob/master/_includes/social-share.html). + +Let's say you wanted to replace the LinkedIn button with a Reddit one. Simply replace the HTML with the following: + +```html +{% raw %}<a href="https://www.reddit.com/submit?url={{ page.url | absolute_url | url_encode }}&title={{ page.title }}" class="btn" title="{{ site.data.ui-text[site.locale].share_on_label }} Reddit"><i class="fab fa-fw fa-reddit" aria-hidden="true"></i><span> Reddit</span></a>{% endraw %} +``` + +The important parts to change are: + +1. Share point URL *eg. `https://www.reddit.com/submit?url=` +2. Link `title` +3. [Font Awesome icon](http://fontawesome.io/icons/) (`fa-` class) +4. Link label + +![Reddit social share link button]({{ "/assets/images/mm-social-share-links-reddit-gs.png" | relative_url }}) + +To change the color of the button use one of the built in [utility classes]({{ "/docs/utility-classes/#buttons" | relative_url }}). Or you can create a new button class to match whatever color you want. + +Under the `$social` color map in `assets/_scss/_buttons.scss` simply add a name (this will be appened to `btn--`) that matches the new button class. In our case `reddit` ~> `.btn--reddit`. + +```scss +$social: +(facebook, $facebook-color), +(twitter, $twitter-color), +(linkedin, $linkedin-color), +(reddit, #ff4500); +``` + +**ProTip:** For bonus points you can add it as a Sass `$variable` that you set in `_variables.scss` like the other ["brand" colors](http://brandcolors.net/). +{: .notice--info} + +Add the new `.btn--reddit` class to the `<a>` element from earlier, [compile `main.css`]({{ "/docs/stylesheets/" | relative_url }}) and away you go. + +```html +{% raw %}<a href="https://www.reddit.com/submit?url={{ page.url | relative_url }}&title={{ page.title }}" class="btn btn--reddit" title="{{ site.data.ui-text[site.locale].share_on_label }} Reddit"><i class="fab fa-fw fa-reddit" aria-hidden="true"></i><span> Reddit</span></a>{% endraw %} +``` + +![Reddit social share link button]({{ "/assets/images/mm-social-share-links-reddit-color.png" | relative_url }}) diff --git a/docs/11-posts.md b/docs/11-posts.md new file mode 100644 index 00000000..8deb22ed --- /dev/null +++ b/docs/11-posts.md @@ -0,0 +1,30 @@ +Posts are stored in the `_posts` directory and named according to the `YEAR-MONTH-DAY-title.MARKUP` format as per [the usual](https://jekyllrb.com/docs/posts/). + +Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit numbers, and `MARKUP` is the file extension representing the format used in the file. For example, the following are examples of valid post filenames: + +``` +2016-07-20-writing-jekyll-posts.md +2015-01-03-static-site-generators.markdown +``` + +**Recommended Front Matter Defaults:** + +```yaml +defaults: + # _posts + - scope: + path: "" + type: posts + values: + layout: single + author_profile: true + read_time: true + comments: true + share: true + related: true +``` + +Adding the above to `_config.yml` will assign the `single` layout and enable: *author profile*, *reading time*, *comments*, [*social sharing links*]({{ "/docs/layouts/#social-sharing-links" | relative_url }}), and *related posts*, for all posts. + +**ProTip:** Remember to write unique `excerpt` descriptions for each post for improved SEO and archive listings. +{: .notice--info} \ No newline at end of file diff --git a/docs/12-pages.md b/docs/12-pages.md new file mode 100644 index 00000000..d5ea6aa9 --- /dev/null +++ b/docs/12-pages.md @@ -0,0 +1,59 @@ +The initial layout of the pages is defined by creating a special file on the SPIFFS file system. +This layout is displayed each time HASP starts up. +You can upload this file *(and other resource assets like fonts and images)* in the web interface Configuration > HASP Settings. + +### pages.jsonl + +The location of this file is `/pages.jsonl` in the root of the filesystem. +It uses the [JSON Lines format](http://www.jsonlines.org) with one json object per line. +Each line should contain exactly **one** valid json object and end with a line-break `\n` *(not a comma)*. + +The file is interpreted **line-by-line**. +When a malformed line is encountered, the processing of the rest of the file stops. +If you are missing objects, check the logs to see which line was processed last. +You probably have a typo in the following line which blocks parsing the rest of the file. + +> **Note**</br>The complete file in its entirety is *not* a valid json file. +> Each individual line however must be a valid json object. +> The file extension is `.jsonl` and not `.json`. + +### Objects +Each line in `pages.jsonl` creates **one object** on a page and has to be in the json format. +The order of objects dictates the layer on the page from bottom to top. + +Example Objects +```json +{"page":2,"id":1,"objid":12,"x":5,"y":20,"h":50,"w":50,"enabled":"true","hidden":"false"} +{"page":2,"id":2,"objid":50,"x":5,"y":120,"h":90,"w":50,"enabled":"false","hidden":"false"} +``` + +Once the object is created, you can reference it with `p[x].b[y]` where `x` is the pagenumber and `y` is the id of the object. + +for example: +``` +p[2].b[1].w=100 +p[2].b[2].hidden=true +``` + +## Comments +If any of the required `id` or `objid` properties are missing -*and the line is still valid json*- then it is interpreted as a comment. + +You can also use the `page` parameter in a comment to set the default page for new objects that don't have a `page` parameter. + +Example 1: Add a comment on a single line that is ignored. +```json +{"comment":" ----------- Page 2 layout ------------"} +``` + +Example 2: Set the default `page` for next object(s) to `3` besides adding a comment as well. + +```json +{"page":3,"comment":" ---- My Awesome Color Picker Layout ----"} +``` + +If you then omit the `page` parameter in the lines below this comment, those objects will appear by default on page `3`. + +> Note: If the line is not valid json, the parsing of the rest of the file is also stopped. + +## Blank Lines +Blank lines are allowed for readability and are ignored. diff --git a/docs/13-objects.md b/docs/13-objects.md new file mode 100644 index 00000000..ebb45282 --- /dev/null +++ b/docs/13-objects.md @@ -0,0 +1,247 @@ +## Common Properties + +These are the common properties shared among all objects: + +<style> +table th:first-of-type { + width: 12%; +} +table th:nth-of-type(2) { + width: 12%; +} +table th:nth-of-type(3) { + width: 12%; +} +table th:nth-of-type(4) { + width: 12%; +} +table th:last-of-type { + width: 48%; +} +</style> + +| Property | Value | Required | Default | Description | +|:---------|:----------:|:--------:|:-------:|:------------| +| id | 0-255 | yes | n/a | ID of the object on this page | +| objid | 0-255 | yes | n/a | ID of the object type *(see below)* | +| page | 0-255 | no | n/a | ID of the page the object appears on | +| x | int16 | no | 0 | horizontal position on the page | +| y | int16 | no | 0 | vertical position on the page | +| w | int16 | no | 0 | width of the object | +| h | int16 | no | 0 | height of the object | +| enabled | true/false | no | true | object is clickable | +| hidden | true/false | no | false | object is hidden | +| opacity | 0-255 | no | 255 | how much the the object is opaque | + +If the `page` parameter is not present, the object is placed on the same page as the _previous object_. If `page` is not specified for the first object either, the _current page_ being displayed is used. + +The maximum number of pages and objects is limited by the memory available in the MCU. + +`"page":254` indicates that the object is visible on every page. It can be used for example to specify a static menu bar. +You can still hide the object on select pages if needed. Objects on this page appear on top of any objects on the underlying page. + + +## Object Types + +Each object type is an ID that indicates which object type that line represents. +Besides the common properties listed above, each object type can have specific properties. + + +### Button +**objid:10** + +<div align="center"> + +![lv_btn](assets/images/objects/lv_ex_btn_1.png) + +</div> + +<details open=""><summary>Show Jsonl Code (Click to expand)</summary> + +```json +{"page":0,"comment":"---------- Page 0 ----------"} +{"objid":10,"id":1,"x":10,"y":45,"w":220,"h":55,"toggle":"TRUE","txt":"Push Me \uf0a6"} +``` +</details> + +| Property | Value | Required | Default | Description +|----------|------------|----------|---------|-------------- +| toggle | boolean | no | false | When enabled, creates a toggle-on/toggle-off button. If false, creates a normal button +| val | int16 | no | 0 | The value: 1 for toggled, 0 for untoggled +| txt | string | no | "" | The text of the label +| mode | string | no | expand | The wrapping mode of long text labels + +Normal Switches send touch events out as they occor. The possible events are: + +- DOWN: Occurs when a button goes from unpressed to being pressed +- SHORT: The button was released within a short time i.e. a short click has occured +- LONG: Event is send when the button is *still* being pressed after the threshold time +<!-- - HOLD: The HOLD event is repeated every 400ms while the button is still pressed --> +- UP: The button is released after being pressing for a LONG threshold time. +- LOST: This event occurs when the object looses the focus while the screen is still being touched + +Toggle Switches only send out their new value (0 or 1) when toggled. + +Possible wrapping modes are: expand, break, dots, scroll and loop + +### Checkbox +**objid:11** + +![lv_checkbox](assets/images/objects/lv_ex_checkbox_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|----------|------------|----------|------------|-------------- +| val | int16 | no | 0 | The value: 1 for checked, 0 for unchecked +| txt | string | no | "Checkbox" | The label of the checkbox + +### Text Label +**objid:12** + +![lv_label](assets/images/objects/lv_ex_label_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|----------|------------|----------|------------|-------------- +| txt | string | no | "Text" | The text of the label +| mode | string | no | expand | The wrapping mode of long text labels + +Possible wrapping modes are: expand, break, dots, scroll and loop + +```json +{"page":2,"id":1,"objid":12,"h":24,"w":120,"txt":"\ufe05 Icon Demo"} +``` + +### Arc +**objid:22** + +![lv_arc](assets/images/objects/lv_ex_arc_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|-----------|------------|----------|---------|-------------- +| min | int16 | no | 0 | +| max | int16 | no | 100 | +| val | int16 | no | 0 | +| rotation | int16 | no | 0 | +| type | int16 | no | normal | normal, reverse, symetrical + + +### Spinner +**objid:21** + +![lv_spinner](assets/images/objects/lv_ex_spinner_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|-----------|------------|----------|---------|-------------- +| speed | int16 | no | 1000 | The time for 1 furn in ms +| direction | int16 | no | 100 | 0 for clockwise, 1 for counter-clockwise +| thickness | int16 | no | dep. on theme | The width of the arcline + +### Colorpicker +**objid:20** + +![lv_cpicker](assets/images/objects/lv_ex_cpicker_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|----------|------------|----------|---------|-------------- +| val | uint16 | no | 0 | The selected color in RBG565 format +| color | hex string | no | 0 | The selected color in html format #rrggbb +| rect | boolean | no | false | True if the color picker has a rectangular shape like a slider. False for a circular shape. + + +### Slider +**objid:30** + +![lv_slider](assets/images/objects/lv_ex_slider_1.png){: .align-center} + +| Property | Value | Required | Default | +|----------|------------|----------|---------| +| min | int16 | no | 0 | +| max | int16 | no | 100 | +| val | int16 | no | 0 | + +### Double Slider +**objid:30** + +| Property | Value | Required | Default | +|----------|------------|----------|---------| +| min | int16 | no | 0 | +| max | int16 | no | 100 | +| val | int16 | no | 0 | + + +### Gauge +**objid:31** + +![lv_gauge](assets/images/objects/lv_ex_gauge_1.png){: .align-center} + +| Property | Value | Required | Default | +|----------|------------|----------|---------| +| min | int16 | no | 0 | +| max | int16 | no | 100 | +| val | int16 | no | 0 | + + +### Progressbar +**objid:32** + +![lv_bar](assets/images/objects/lv_ex_bar_1.png){: .align-center} + +| Property | Value | Required | Default | +|----------|------------|----------|---------| +| min | int16 | no | 0 | +| max | int16 | no | 100 | +| val | int16 | no | 0 | + + +### Switch +**objid:40** + +![lv_switch](assets/images/objects/lv_ex_switch_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|------------|------------|----------|---------|--------------- +| val | int16 | no | 0 | The value: 1 for on, 0 for off + +### LED Indicator +**objid:41** + +![lv_led](assets/images/objects/lv_ex_led_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|------------|------------|----------|---------|--------------- +| val | byte | no | 0 | The brightness of the indicator 0-255 + +### Dropdown List +**objid:50** + +![lv_dropdown](assets/images/objects/lv_ex_dropdown_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|----------|------------|----------|---------|-------------------------- +| options | string | no | "" | The items separated by \n +| val | int16 | no | 0 | The number of the selected item +| txt | string | no | "" | *Read-only* The text of the selected item + +To change the currently selected item, use the `val` attribute. +To change the items in the list, use the `options` attribute. + +When the item is changed both `val` and `txt` of the newly selected item are send out. + + +### Roller +**objid:51** + +![lv_roller](assets/images/objects/lv_ex_roller_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|----------|------------|----------|---------|-------------------------- +| options | string | no | "" | The items separated by \n +| val | int16 | no | 0 | The number of the selected item +| txt | string | no | "" | *Read-only* The text of the selected item +| rows | int8 | no | 3 | The number ow rows that are visible + +Note: A roller does not use the `h` attribute to set its height, but uses the rows to set the visible number of rows instead. + +To change the currently selected item, use the `val` attribute. +To change the items in the list, use the `options` attribute. + +When the item is changed both `val` and `txt` of the newly selected item are send out. diff --git a/docs/14-styling.md b/docs/14-styling.md new file mode 100644 index 00000000..074e4ea6 --- /dev/null +++ b/docs/14-styling.md @@ -0,0 +1,315 @@ + +## Styling Properties + +You can adjust the appearance of objects by changing the foreground, background and/or border color of each object. + +## Object Types + +Each object type is an ID that indicates which object type that line represents. +Besides the common properties listed above, each object type can have specific properties. + + +## Button +**objid:10** + +A button can have 3 states. All the following parameters can be appended by a number to change the appearance of that state only: +- 0: Released +- 1: Pressed +- 2: Disabled + +Or if the postfix index is ommited, then the default state 0 or Pressed is used. + +A button can accept the attributes of the following groups: +- Background +- Border +- Outline +- Shadow +- Value + +## Attribute groups + +### Padding and Margin + +Padding sets the space on the inner sides of the edges. It means "I don't want my children too close to my sides, so keep this space".Padding inner set the "gap" between the children. Margin sets the space on the outer side of the edges. It means "I want this space around me". + +Objects use them to set spacing. See the documentation of the objects for the details. + +| Property | Type | Required | Default | Description +|----------|------------|----------|---------|-------------- +| pad_top | int | Set the padding on the top +| pad_bottom | int | Set the padding on the bottom +| pad_left | int | Set the padding on the left +| pad_right | int | Set the padding on the right +| pad_inner | int | Set the padding inside the object between children +| margin_top | int | Set the margin on the top +| margin_bottom | int | Set the margin on the bottom +| margin_left | int | Set the margin on the left +| margin_right | int | Set the margin on the right + +### Background + +| Property | Type | Required | Default | Description +|----------|------------|----------|---------|-------------- +| bg_opa | byte | no | "" | The background opacity level +| bg_color | color | no | true | The background color +| bg_grad_color | color | no | 0 | The background gradient color +| bg_grad_dir | [0..2]| no | expand | 0 = None, 1 = Horizontal, 2 = Vertical +| bg_grad_stop | byte | no | expand | Specifies where the gradient should stop. 0: at left/top most position, 255: at right/bottom most position. Default value: 255. +| bg_main_stop | byte | no | expand | Specifies where should the gradient start. 0: at left/top most position, 255: at right/bottom most position. Default value: 0. + +### Border + +The border is drawn on top of the background. It has radius rounding. + +| Property | Type | Required | Default | Description +|----------|------------|----------|---------|-------------- +| border_color | color| Specifies the color of the border +| border_opa | byte | Specifies opacity of the border +| border_width | byte | Set the width of the border +| border_side | byte | Specifies which sides of the border to draw. Can be 0=LV_BORDER_SIDE_NONE/1=LEFT/2=RIGHT/4=TOP/8=BOTTOM/15=FULL. A sum of these values is also possible to select specific sides. +| border_post | bool | If `true` the border will be drawn after all children have been drawn. + +### Shadow + +The shadow is a blurred area under the object. + +| Property | Type | Required | Default | Description +|----------|------------|----------|---------|-------------- +| shadow_color | color | Specifies the color of the shadow +| shadow_opa | byte | Specifies opacity of the shadow +| shadow_width | int16 | Set the width (blur size) of the outline +| shadow_ofs_x | int16 | Set the an X offset for the shadow +| shadow_ofs_y | int16 | Set the an Y offset for the shadow +| shadow_spread | byte | make the shadow larger than the background in every direction by this value + +### Value + +Value is an arbitrary text drawn to the background. It can be a lightweighted replacement of creating label objects. + +| Property | Type | Required | Default | Description +|----------|------------|----------|---------|-------------- +| value_str | string | Text to display. Only the pointer is saved! (Don't use local variable with lv_style_set_value_str, instead use static, global or dynamically allocated data) +| value_color | color | Color of the text +| value_opa | byte | Opacity level of the text [0-255] +| value_font | byte | The font ID +| value_letter_space | int | Letter space of the text +| value_line_space | int | Line space of the text +| value_align | align | Alignment of the text. Can be LV_ALIGN_.... Default value: LV_ALIGN_CENTER. +| value_ofs_x | int | X offset from the original position of the alignment +| value_ofs_y | int | Y offset from the original position of the alignment + +### Text + +Properties for textual object. + +| Property | Type | Required | Default | Description +|----------|------------|----------|---------|-------------- +| text_color | color | Color of the text +| text_opa | byte | Opacity level of the text [0-255] +| text_font | byte | Font ID +| text_letter_space | int | Letter space of the text +| text_line_space | int | Line space of the text +| text_decor | byte | Add text decoration. 0=None, 1=Underline, 2=Strikethrough, 3=Underline&Strikethrough +| text_sel_color | color | Set background color of text selection + +### Line + +n/a + +### Image + +n/a + +### Outline + +n/a + +### Pattern + +n/a + +### Transitions + +n/a + + + + +### Checkbox +**objid:11** + +![lv_checkbox](assets/images/objects/lv_ex_checkbox_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|----------|------------|----------|------------|-------------- +| val | int16 | no | 0 | The value: 1 for checked, 0 for unchecked +| txt | string | no | "Checkbox" | The label of the checkbox + +### Text Label +**objid:12** + +![lv_label](assets/images/objects/lv_ex_label_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|----------|------------|----------|------------|-------------- +| txt | string | no | "Text" | The text of the label +| mode | string | no | expand | The wrapping mode of long text labels + +Possible wrapping modes are: expand, break, dots, scroll and loop + +```json +{"page":2,"id":1,"objid":12,"h":24,"w":120,"txt":"\ufe05 Icon Demo"} +``` + +### Spinner +**objid:21** + +![lv_spinner](assets/images/objects/lv_ex_spinner_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|-----------|------------|----------|---------|-------------- +| speed | int16 | no | 1000 | The time for 1 furn in ms +| direction | int16 | no | 100 | 0 for clockwise, 1 for counter-clockwise +| thickness | int16 | no | dep. on theme | The width of the arcline + +### Colorpicker +**objid:20** + +![lv_cpicker](assets/images/objects/lv_ex_cpicker_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|----------|------------|----------|---------|-------------- +| val | uint16 | no | 0 | The selected color in RBG565 format +| color | hex string | no | 0 | The selected color in html format #rrggbb +| rect | boolean | no | false | True if the color picker has a rectangular shape like a slider. False for a circular shape. + + +### Slider +**objid:30** + +![lv_slider](assets/images/objects/lv_ex_slider_1.png){: .align-center} + +| Property | Value | Required | Default | +|----------|------------|----------|---------| +| min | int16 | no | 0 | +| max | int16 | no | 100 | +| val | int16 | no | 0 | + +### Double Slider +**objid:30** + +| Property | Value | Required | Default | +|----------|------------|----------|---------| +| min | int16 | no | 0 | +| max | int16 | no | 100 | +| val | int16 | no | 0 | + + +### Gauge +**objid:31** + +![lv_gauge](assets/images/objects/lv_ex_gauge_1.png){: .align-center} + +| Property | Value | Required | Default | +|----------|------------|----------|---------| +| min | int16 | no | 0 | +| max | int16 | no | 100 | +| val | int16 | no | 0 | + + +### Progressbar +**objid:32** + +![lv_bar](assets/images/objects/lv_ex_bar_1.png){: .align-center} + +| Property | Value | Required | Default | +|----------|------------|----------|---------| +| min | int16 | no | 0 | +| max | int16 | no | 100 | +| val | int16 | no | 0 | + + +### Switch +**objid:40** + +![lv_switch](assets/images/objects/lv_ex_switch_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|------------|------------|----------|---------|--------------- +| val | int16 | no | 0 | The value: 1 for on, 0 for off + +### LED Indicator +**objid:41** + +![lv_led](assets/images/objects/lv_ex_led_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|------------|------------|----------|---------|--------------- +| val | byte | no | 0 | The brightness of the indicator 0-255 + +### Dropdown List +**objid:50** + +![lv_dropdown](assets/images/objects/lv_ex_dropdown_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|----------|------------|----------|---------|-------------------------- +| options | string | no | "" | The items separated by \n +| val | int16 | no | 0 | The number of the selected item +| txt | string | no | "" | *Read-only* The text of the selected item + +To change the currently selected item, use the `val` attribute. +To change the items in the list, use the `options` attribute. + +When the item is changed both `val` and `txt` of the newly selected item are send out. + + +### Roller +**objid:51** + +![lv_roller](assets/images/objects/lv_ex_roller_1.png){: .align-center} + +| Property | Value | Required | Default | Description +|----------|------------|----------|---------|-------------------------- +| options | string | no | "" | The items separated by \n +| val | int16 | no | 0 | The number of the selected item +| txt | string | no | "" | *Read-only* The text of the selected item +| rows | int8 | no | 3 | The number ow rows that are visible + +Note: A roller does not use the `h` attribute to set its height, but uses the rows to set the visible number of rows instead. + +To change the currently selected item, use the `val` attribute. +To change the items in the list, use the `options` attribute. + +When the item is changed both `val` and `txt` of the newly selected item are send out. + +## Example file + +This is a real-world demo `pages.jsonl` file: + +```json +{"comment":"---------- Page 0 ----------"} +{"objid":10,"id":1,"page":0,"x":10,"y":45,"w":220,"h":55,"toggle":"TRUE","txt":"Toggle Me \uf0a6"} +{"objid":11,"id":2,"page":0,"x":10,"y":100,"w":220,"h":55,"txt":"Checkbox 1"} +{"objid":12,"id":3,"page":0,"x":10,"y":10,"w":220,"h":30,"txt":"Text Label 1","align":1,"padh":50} +{"objid":40,"id":4,"page":0,"x":70,"y":205,"w":100,"h":55} +{"objid":41,"id":5,"page":0,"x":10,"y":205,"w":55,"h":55} +{"objid":50,"id":6,"page":0,"x":10,"y":150,"w":150,"txt":"\uf007 Option 1\n\uf007 Option 2\n\uf007 Option 3"} +{"objid":21,"id":7,"page":0,"x":165,"y":140,"w":70,"h":70} +{"comment":"---------- Page 1 ----------"} +{"objid":30,"id":1,"page":1,"x":10,"y":170,"w":200,"h":50} +{"objid":31,"id":3,"page":1,"x":13,"y":10,"w":100,"h":100} +{"objid":32,"id":4,"page":1,"x":10,"y":110,"w":200,"h":50} +{"objid":33,"id":5,"page":1,"x":127,"y":10,"w":100,"h":100} +{"objid":12,"id":10,"page":1,"x":0,"y":0,"w":70,"h":50,"parentid":5,"txt":"\uf00c OK"} +{"comment":"---------- Page 2 ----------"} +{"objid":20,"id":1,"page":2,"x":20,"y":0,"w":200,"h":200} +{"objid":20,"id":2,"page":2,"x":20,"y":210,"w":200,"h":50,"rect":"TRUE"} +{"comment":"---------- Page 3 ----------"} +{"objid":50,"id":1,"page":3,"x":10,"y":10,"w":220,"txt":"Spring\nSummer\nAutumn\nWinter"} +{"objid":51,"id":2,"page":3,"x":40,"y":50,"w":160,"txt":"2018\n2019\n2020\n2021\n2022\n2023\n2024","rows":4} +{"comment":"---------- Page 254 ----------"} +{"objid":10,"id":1,"page":254,"x":0,"y":270,"w":75,"h":50,"opacity":100,"txt":"\uF053 Prev"} +{"objid":10,"id":2,"page":254,"x":75,"y":270,"w":90,"h":50,"opacity":100,"txt":"\uF015 Home"} +{"objid":10,"id":3,"page":254,"x":165,"y":270,"w":75,"h":50,"opacity":100,"txt":"Next \uF054"} +``` \ No newline at end of file diff --git a/docs/15-example-pages.md b/docs/15-example-pages.md new file mode 100644 index 00000000..9f6239ce --- /dev/null +++ b/docs/15-example-pages.md @@ -0,0 +1,50 @@ + +## Example file + +This is a real-world example of a `pages.jsonl` file: + +<details> +<summary>Show Jsonl Code (Click to expand)</summary> + +```json +{"page":0,"comment":"---------- Page 0 ----------"} +{"objid":10,"id":1,"x":10,"y":45,"w":220,"h":55,"toggle":"TRUE","txt":"Push Me \uf0a6"} +{"objid":11,"id":2,"x":10,"y":100,"w":220,"h":55,"txt":"A Checkbox"} +{"objid":12,"id":3,"x":10,"y":10,"w":220,"h":30,"txt":"My Label","align":1,"padh":50} +{"objid":40,"id":4,"x":70,"y":205,"w":100,"h":55} +{"objid":41,"id":5,"x":10,"y":205,"w":55,"h":55} +{"objid":50,"id":6,"x":10,"y":150,"w":150,"options":"\uf007 Line 1\n\uf007 Line 2\n\uf007 Line 3"} +{"objid":21,"id":7,"x":165,"y":140,"w":70,"h":70} + +{"page":1,"comment":"---------- Page 1 ----------"} +{"objid":30,"id":1,"x":10,"y":170,"w":200,"h":50} +{"objid":31,"id":3,"x":13,"y":10,"w":100,"h":100} +{"objid":32,"id":4,"x":10,"y":110,"w":200,"h":50} +{"objid":33,"id":5,"x":127,"y":10,"w":100,"h":100} +{"objid":12,"id":10,"x":0,"y":0,"w":70,"h":50,"parentid":5,"txt":"\uf00c OK"} + +{"comment":"---------- Page 2 ----------"} +{"objid":20,"id":1,"page":2,"x":20,"y":0,"w":200,"h":200} +{"objid":20,"id":2,"page":2,"x":20,"y":210,"w":200,"h":50,"rect":"TRUE"} + +{"page":3,"comment":"---------- Page 3 ----------"} +{"objid":50,"id":1,"x":10,"y":10,"w":220,"options":"Spring\nSummer\nAutumn\nWinter"} +{"objid":51,"id":2,"x":40,"y":50,"w":160,"rows":3,"options":"2020\n2021\n2022\n2023\n2024"} + +{"page":254,"comment":"---------- Page 254 ----------"} +{"objid":10,"id":1,"x":0,"y":270,"w":75,"h":50,"opacity":100,"txt":"\uF053 Prev"} +{"objid":10,"id":2,"x":75,"y":270,"w":90,"h":50,"opacity":100,"txt":"\uF015 Home"} +{"objid":10,"id":3,"x":165,"y":270,"w":75,"h":50,"opacity":100,"txt":"Next \uF054"} +``` + +</details> + +## Result + +Page 0 + +Page 1 + +Page 2 + +Page 3 \ No newline at end of file diff --git a/docs/16-compiling.md b/docs/16-compiling.md new file mode 100644 index 00000000..8dc813d9 --- /dev/null +++ b/docs/16-compiling.md @@ -0,0 +1,22 @@ +## Cloning + +Make sure to add the `--recursive` parameter when cloning the project from GitHub. Otherwise git will not download the required submodules in the `/lib` subdirectory. + +```bash +git clone --recursive https://github.com/fvanroie/hasp-lvgl +``` + +If you already cloned hasp-lvgl without the submodules, you can fetch the submodules seperately using: + +```bash +git submodule update --init --recursive +``` + +To switch to a different branch use: + +```bash +git clone --recursive https://github.com/fvanroie/hasp-lvgl +cd hasp-lvgl +git checkout 0.2.0 +git submodule update --init --recursive +``` diff --git a/docs/17-javascript.md b/docs/17-javascript.md new file mode 100644 index 00000000..ea53be39 --- /dev/null +++ b/docs/17-javascript.md @@ -0,0 +1,60 @@ + +The theme's `assets/js/main.min.js` script is built from several vendor, jQuery plugins, and other scripts found in [`assets/js/`](https://github.com/mmistakes/minimal-mistakes/tree/master/assets/js). + +```bash +minimal mistakes +├── assets +| ├── js +| | ├── plugins +| | | ├── gumshoe.js # simple scrollspy +| | | ├── jquery.ba-throttle-debounce.js # rate-limit functions +| | | ├── jquery.fitvids.js # fluid width video embeds +| | | ├── jquery.greedy-navigation.js # priority plus navigation +| | | ├── jquery.magnific-popup.js # responsive lightbox +| | | └── smooth-scroll.js # make same-page links scroll smoothly +| | ├── vendor +| | | └── jquery +| | | └── jquery-3.4.1.js +| | ├── _main.js # jQuery plugin settings and other scripts +| | └── main.min.js # concatenated and minified theme script +``` + +## Customizing + +To modify or add your own scripts include them in [`assets/js/_main.js`](https://github.com/mmistakes/minimal-mistakes/blob/master/assets/js/_main.js) and then rebuild using `npm run build:js`. See below for more details. + +If you add additional scripts to `assets/js/plugins/` and would like them concatenated with the others, be sure to update the `uglify` script in [`package.json`](https://github.com/mmistakes/minimal-mistakes/blob/master/package.json). Same goes for scripts that you remove. + +You can also add scripts to the `<head>` or closing `</body>` elements by adding paths to following arrays in `_config.yml`. + +**Example:** + +```yaml +head_scripts: + - https://code.jquery.com/jquery-3.3.1.min.js + - /assets/js/your-custom-head-script.js +footer_scripts: + - /assets/js/your-custom-footer-script.js +after_footer_scripts: + - /assets/js/custom-script-loads-after-footer.js +``` + +**Note:** If you assign `footer_scripts` the theme's `/assets/js/main.min.js` file will be deactivated. This script includes jQuery and various other plugins that you'll need to find replacements for and include separately. +{: .notice--warning} + +--- + +## Build process + +In an effort to reduce dependencies a set of [**npm scripts**](https://css-tricks.com/why-npm-scripts/) are used to build `main.min.js` instead of task runners like [Gulp](http://gulpjs.com/) or [Grunt](http://gruntjs.com/). If those tools are more your style then by all means use them instead :wink:. + +To get started: + +1. Install [Node.js](http://nodejs.org/). +2. `cd` to the root of your project. +3. Install all of the dependencies by running `npm install`. + +**Note:** If you upgraded from a previous version of the theme be sure you copied over [`package.json`](https://github.com/{{ site.repository }}/blob/master/package.json) prior to running `npm install`. +{: .notice--warning} + +If all goes well, running `npm run build:js` will compress/concatenate `_main.js` and all plugin scripts into `main.min.js`. diff --git a/docs/18-history.md b/docs/18-history.md new file mode 100644 index 00000000..13e92dc7 --- /dev/null +++ b/docs/18-history.md @@ -0,0 +1,1460 @@ + +## [4.19.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.19.2) + +### Enhancements + +- Add support for bilibili videos in [responsive video helper](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#responsive-video-embed). [#2512](https://github.com/mmistakes/minimal-mistakes/pull/2512) +- Add Myanmar (Burmese) localized UI text strings. [#2500](https://github.com/mmistakes/minimal-mistakes/pull/2500) +- Improve author links underline on hover. [#2472](https://github.com/mmistakes/minimal-mistakes/pull/2472) +- Add documentation for applying Front Matter defaults to jekyll-archives pages. [#2466](https://github.com/mmistakes/minimal-mistakes/pull/2466) +- Add missing Vietnamese translations. [#2459](https://github.com/mmistakes/minimal-mistakes/pull/2459) [#2486](https://github.com/mmistakes/minimal-mistakes/pull/2486) +- Fix Finnish localized UI text strings. [#2455](https://github.com/mmistakes/minimal-mistakes/pull/2455) +- Clarify documentation that Lunr only searches documents in collections. [#2450](https://github.com/mmistakes/minimal-mistakes/pull/2450) +- Add guide on applying Front Matter defaults to jekyll-archives pages [#2466](https://github.com/mmistakes/minimal-mistakes/pull/2466) + +### Bug Fixes + +- Fix typo in configuration documentation. [#2497](https://github.com/mmistakes/minimal-mistakes/pull/2497) +- Fix "Follow menu falls under post links" on small screens. [#2479](https://github.com/mmistakes/minimal-mistakes/issues/2479) +- Hide index page from page-archive. [#2482](https://github.com/mmistakes/minimal-mistakes/pull/2482) + +## [4.19.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.19.1) + +### Enhancements + +- Add [Dracula](https://draculatheme.com/) Base16 syntax highlighting theme Sass variables to [stylesheets documentation](https://mmistakes.github.io/minimal-mistakes/docs/stylesheets/#syntax-highlighting). [#2438](https://github.com/mmistakes/minimal-mistakes/pull/2438) +- Update links to `HTTPS` and remove Google+ from configuration documentation. [#2432](https://github.com/mmistakes/minimal-mistakes/pull/2432) +- Use `first_page_path` from jekyll-paginate-v2 if available. [#2431](https://github.com/mmistakes/minimal-mistakes/pull/2431) +- Update onchange and uglify-js dependencies. +- Update smooth-scroll.js to `v16.1.2`. [#2430](https://github.com/mmistakes/minimal-mistakes/issues/2430) + +### Bug Fixes + +- Fix author profile links `z-index` order on small screens. [#2440](https://github.com/mmistakes/minimal-mistakes/issues/2440) + +## [4.19.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.19.0) + +### Enhancements + +- Add "click" overlay to close masthead and follow button menus when open. [#1168](https://github.com/mmistakes/minimal-mistakes/issues/1168) +- Remove deprecated Staticman v1 configurations from `_config.yml`. [#2386](https://github.com/mmistakes/minimal-mistakes/issues/2386) +- Use `relative_url` and `absolute_url` filters where possible. [#2387](https://github.com/mmistakes/minimal-mistakes/pull/2387) +- Improve headline hierarchy and add Sass specific variables `$h-size-x`. [#2423](https://github.com/mmistakes/minimal-mistakes/issues/2423) +- Improve accessibility of `default` skin by increasing color contrast of text and links. +- Hide posts with `hidden: true` YAML front matter from appearing in listings. [#2345](https://github.com/mmistakes/minimal-mistakes/pull/2345) +- Add Irish (Gaeilge) localized UI text strings. [#2422](https://github.com/mmistakes/minimal-mistakes/pull/2422) +- Remove `box-shadow` on radio and checkbox inputs. [#2398](https://github.com/mmistakes/minimal-mistakes/pull/2398) +- Bump Jekyll gem dependency to `v3.7`. + +### Bug Fixes + +- Fix documentation around using `bundle info` command. [#2425](https://github.com/mmistakes/minimal-mistakes/pull/2425) +- Fix rake vulnerability in `.gemspec` file. +- Fix Staticman v2 comment submission. [#2402](https://github.com/mmistakes/minimal-mistakes/pull/2402) +- Fix repeated site base path for masthead logo. [#2385](https://github.com/mmistakes/minimal-mistakes/pull/2385) + +## [4.18.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.18.1) + +### Bug Fixes + +- Fix compatibility issue with jekyll-paginate-v2. [#2381](https://github.com/mmistakes/minimal-mistakes/pull/2381) + +## [4.18.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.18.0) + +### Enhancements + +- Allow `home` layout to display posts without pagination. [#2378](https://github.com/mmistakes/minimal-mistakes/pull/2378) +- Add links to high resolution skin screenshots in README. [#2363](https://github.com/mmistakes/minimal-mistakes/issues/2363) +- Update README and LICENSE. [#2367](https://github.com/mmistakes/minimal-mistakes/pull/2367) +- Update `.gitignore` file. [#2366](https://github.com/mmistakes/minimal-mistakes/pull/2366) +- Allow override of page excerpt in hero header via `tagline` YAML front matter. [#2307](https://github.com/mmistakes/minimal-mistakes/pull/2307) +- Exclude `package-lock.json` from Jekyll build. [#2364](https://github.com/mmistakes/minimal-mistakes/pull/2364) +- Use `%-d` instead of `%d` so displayed dates aren't padded with zero. [#2359](https://github.com/mmistakes/minimal-mistakes/pull/2359) +- Update table of contents helper (`toc.html`) to [v1.0.8](https://github.com/allejo/jekyll-toc/releases). [#2355](https://github.com/mmistakes/minimal-mistakes/pull/2355) +- Add missing Dutch localized UI text strings. [#2321](https://github.com/mmistakes/minimal-mistakes/pull/2321) +- Support page header (hero) in `archive-taxonomy` layout. [#2320](https://github.com/mmistakes/minimal-mistakes/pull/2320) +- Add social icon color for Keybase. [#2302](https://github.com/mmistakes/minimal-mistakes/pull/2302) + +### Bug Fixes + +- Fix JavaScript comments in Disqus include to be compatible with `compress` layout. [#2373](https://github.com/mmistakes/minimal-mistakes/pull/2373) +- Fix wrong newline concatenation in SEO description [#2368](https://github.com/mmistakes/minimal-mistakes/pull/2368) [#2354](https://github.com/mmistakes/minimal-mistakes/issues/2354) +- Fix Staticman v2/v3 conditional for showing comments. [#2351](https://github.com/mmistakes/minimal-mistakes/pull/2351) +- Fix masthead logo path. [#2332](https://github.com/mmistakes/minimal-mistakes/pull/2332) +- Fix schema.org dates to ISO-8601. [#2339](https://github.com/mmistakes/minimal-mistakes/pull/2339) +- Fix background color of code blocks in notices. [#2328](https://github.com/mmistakes/minimal-mistakes/pull/2328) +- Fix alignment of feature rows when placed next to a sticky sidebar. [#2327](https://github.com/mmistakes/minimal-mistakes/issues/2327) +- Fix `seo_description` in `_includes/seo.html`. [#2326](https://github.com/mmistakes/minimal-mistakes/pull/2326) +- Fix typo in `_config.yml`. [#2319](https://github.com/mmistakes/minimal-mistakes/pull/2319) + +## [4.17.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.17.2) + +### Enhancements + +- Add collection step to documentation about creating a portfolio page. [#2294](https://github.com/mmistakes/minimal-mistakes/pull/2294) +- Replace sticky footer JavaScript with flexbox styles. [#2289](https://github.com/mmistakes/minimal-mistakes/pull/2289) + +### Bug Fixes + +- Fix sticky footer when using MozBar extension. [#2281](https://github.com/mmistakes/minimal-mistakes/issues/2281) + +## [4.17.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.17.1) + +### Enhancements + +- Update Chinese (Simplified) localized UI text strings. [#2286](https://github.com/mmistakes/minimal-mistakes/pull/2286) +- Update list of 3rd party JavaScript used and licenses. [#2276](https://github.com/mmistakes/minimal-mistakes/pull/2276) + +### Bug Fixes + +- Fix indention of nested GFM task lists. [#2283](https://github.com/mmistakes/minimal-mistakes/issues/2283) + +## [4.17.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.17.0) + +### Enhancements + +- Show a permalink anchor when hovering over headings in main content area. [#2251](https://github.com/mmistakes/minimal-mistakes/pull/2251) +- Allow per-page override of `words_per_minute`. [#2250](https://github.com/mmistakes/minimal-mistakes/pull/2250) +- Update [onchange](https://www.npmjs.com/package/onchange) development dependency in `package.json`. [#2241](https://github.com/mmistakes/minimal-mistakes/issues/2241) +- Add Catalan localized UI text strings. [#2237](https://github.com/mmistakes/minimal-mistakes/pull/2237) + +### Bug Fixes + +- Remove extraneous space from Internet Explorer conditional statement. [#2273](https://github.com/mmistakes/minimal-mistakes/pull/2273) +- Fix typo in `_config.yml`. [#2243](https://github.com/mmistakes/minimal-mistakes/pull/2243) +- Replace `http` URLs with `https` where applicable in `_config.yml`. [#2244](https://github.com/mmistakes/minimal-mistakes/pull/2244) + +## [4.16.6](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.16.6) + +### Enhancements + +- Relax Jekyll dependency to allow for version 4.0. +- Add missing Spanish localized UI text strings. [#2229](https://github.com/mmistakes/minimal-mistakes/pull/2229) +- Allow Markdown in author bio. [#2215](https://github.com/mmistakes/minimal-mistakes/pull/2215) + +### Bug Fixes + +- Fix `site.url` in Organization/Person JSON-LD schema. [#1906](https://github.com/mmistakes/minimal-mistakes/issues/1906) +- Remove full stop in some `comment_form_info` UI text strings. [#2220](https://github.com/mmistakes/minimal-mistakes/pull/2220) +- Fix default `site.author` in seo.html [#2230](https://github.com/mmistakes/minimal-mistakes/pull/2230) +- Fix overlapping links (linked to and post's permalink) in post link type. [#2222](https://github.com/mmistakes/minimal-mistakes/issues/2222) + +## [4.16.5](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.16.5) + +### Enhancements + +- Add optional site subtitle to masthead. [#2173](https://github.com/mmistakes/minimal-mistakes/issues/2173) +- Add missing Punjabi and Hindi localized UI text strings. [#2212](https://github.com/mmistakes/minimal-mistakes/pull/2212) +- Add missing Korean localized UI text strings. [#2209](https://github.com/mmistakes/minimal-mistakes/pull/2209) +- Use [Font Awesome Kits](https://blog.fontawesome.com/introducing-font-awesome-kits-7134d1d59959) to use the latest version of icons. [#2184](https://github.com/mmistakes/minimal-mistakes/issues/2184) +- Remove unnecessary console.log in `lunr-en.js` and `lunr-gr.js` JavaScript. [#2193](https://github.com/mmistakes/minimal-mistakes/issues/2193) +- Remove unnecessary `type="text/javascript"` from Google Analytics JavaScript. [#2190](https://github.com/mmistakes/minimal-mistakes/pull/2190) +- Update links and fix typos in documentation. [#2186](https://github.com/mmistakes/minimal-mistakes/pull/2186) +- Add skip links. [#2182](https://github.com/mmistakes/minimal-mistakes/issues/2182) + +### Bug Fixes + +- Fix aria issues with Lunr search form. [#2211](https://github.com/mmistakes/minimal-mistakes/pull/2211) +- Fix missing fallback title for table of contents. + +## [4.16.4](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.16.4) + +### Enhancements + +- Update Brazilian Portuguese localized UI text strings. [#2162](https://github.com/mmistakes/minimal-mistakes/pull/2162) +- Update Font Awesome to v5.8.2. [#2150](https://github.com/mmistakes/minimal-mistakes/pull/2150) +- Add missing Spanish localized UI text strings. [#2149](https://github.com/mmistakes/minimal-mistakes/pull/2149) + +### Bug Fixes + +- Fix arithmetic in `_form.scss` partial. [#2169](https://github.com/mmistakes/minimal-mistakes/pull/2169) +- Fix pound symbol not displaying properly for post categories and tags. [#2156](https://github.com/mmistakes/minimal-mistakes/issues/2156) +- Fix permalink stacking order and click-able area in archives. + +## [4.16.3](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.16.3) + +### Enhancements + +- Update jQuery to v3.4.1. [#2137](https://github.com/mmistakes/minimal-mistakes/issues/2137) +- Update Gumshoe to v5.1.1. [#2140](https://github.com/mmistakes/minimal-mistakes/issues/2140) + +### Bug Fixes + +- Fix JavaScript error when resizing pages with table of contents. [#2140](https://github.com/mmistakes/minimal-mistakes/issues/2140) + +## [4.16.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.16.2) + +### Bug Fixes + +- Revert jQuery back to version v3.3.1, v.3.4.0 causes issues with other plugins that haven't been updated. [#2137](https://github.com/mmistakes/minimal-mistakes/issues/2137) + +## [4.16.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.16.1) + +### Enhancements + +- Update [`compress` layout](https://mmistakes.github.io/minimal-mistakes/docs/layouts/#compress-layout) to v3.1.0. [#2128](https://github.com/mmistakes/minimal-mistakes/pull/2128) +- Update jQuery to v3.4.0. [#2129](https://github.com/mmistakes/minimal-mistakes/pull/2129) + +### Bug Fixes + +- Fix Gumshoe related JavaScript error on pages without a table of contents. [#2124](https://github.com/mmistakes/minimal-mistakes/pull/2124) + +## [4.16.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.16.0) + +### Enhancements + +- Improve search `input` semantics for Lunr and Google search providers. [#2123](https://github.com/mmistakes/minimal-mistakes/pull/2123) +- Allow adding JavaScript files after those bundled in the theme. [#2110](https://github.com/mmistakes/minimal-mistakes/issues/2110) [#2116](https://github.com/mmistakes/minimal-mistakes/pull/2116) +- Add `$max-width` Sass variable for adjusting page content's maximum width. [#2093](https://github.com/mmistakes/minimal-mistakes/pull/2093) +- Add Thai localized UI text strings. [#2111](https://github.com/mmistakes/minimal-mistakes/pull/2111) +- Update Font Awesome to [v5.8.1](https://github.com/FortAwesome/Font-Awesome/releases/tag/5.8.1). [#2102](https://github.com/mmistakes/minimal-mistakes/pull/2102) +- Add missing Vietnamese localized UI text strings. [#2097](https://github.com/mmistakes/minimal-mistakes/pull/2097) +- Replace jQuery Smooth Scroll with Smooth Scroll + Gumshoe. [#2082](https://github.com/mmistakes/minimal-mistakes/pull/2082) +- Add styling for [GFM task lists](https://help.github.com/en/articles/about-task-lists#creating-task-lists). [#2092](https://github.com/mmistakes/minimal-mistakes/issues/2092) +- Update Google Universal Analytics to load async. [#2079](https://github.com/mmistakes/minimal-mistakes/pull/2079) +- Remove Google+ social sharing button, comment provider, and author link configs from theme. +- Add missing Chinese text strings. [#2072](https://github.com/mmistakes/minimal-mistakes/pull/2072) + +### Bug Fixes + +- Fix table of contents active link styling. +- Add missing Hindi localized UI text strings. [#2105](https://github.com/mmistakes/minimal-mistakes/pull/2105) [#2106](https://github.com/mmistakes/minimal-mistakes/pull/2106) +- Fix Brazilian Portuguese text strings. [#2098](https://github.com/mmistakes/minimal-mistakes/pull/2098) +- Fix typo in French `results_found` text string. [#2096](https://github.com/mmistakes/minimal-mistakes/pull/2096) +- Fix figures inside of list elements. [#2094](https://github.com/mmistakes/minimal-mistakes/pull/2094) +- Remove Font Awesome `data-search-pseudo-elements` attribute as it degrades smooth scroll performance. [#2075](https://github.com/mmistakes/minimal-mistakes/issues/2075#issuecomment-472437014) +- Fix footnote links incompatibility with smooth scroll plugin. [#2075](https://github.com/mmistakes/minimal-mistakes/issues/2075) +- Loosen Bundler dependency in ruby gem. + +## [4.15.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.15.2) + +### Enhancements + +- Close search overlay with <kbd>Esc</kbd>. [#2055](https://github.com/mmistakes/minimal-mistakes/pull/2055) +- Update Swedish localized UI text strings. [#2056](https://github.com/mmistakes/minimal-mistakes/pull/2056) +- Update Font Awesome to 5.7.1 and add `data-search-pseudo-elements` attribute. [#2053](https://github.com/mmistakes/minimal-mistakes/pull/2053) +- Add Malayalam localized UI text strings. [#2037](https://github.com/mmistakes/minimal-mistakes/pull/2037) + +### Bug Fixes + +- Fix table of contents errors with non-English characters in the headings. [#2042](https://github.com/mmistakes/minimal-mistakes/pull/2042) +- Fix `site.logo` false positives. [#2026](https://github.com/mmistakes/minimal-mistakes/pull/2026#issuecomment-455770730) +- Add empty `alt` attribute to `site.logo` image. [#2035](https://github.com/mmistakes/minimal-mistakes/pull/2035) + +## [4.15.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.15.1) + +### Bug Fixes + +- Fix empty `<img>` when `site_logo` is not assigned. [#2026](https://github.com/mmistakes/minimal-mistakes/pull/2026#issuecomment-454809876) + +## [4.15.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.15.0) + +### Enhancements + +- Add logo and title customization to the masthead. [#2026](https://github.com/mmistakes/minimal-mistakes/pull/2026) +- Add support to customize `issue-term` for utterances comment provider. [#2022](https://github.com/mmistakes/minimal-mistakes/pull/2022) +- Allow custom canonical url on a page-by-page basis. [#2021](https://github.com/mmistakes/minimal-mistakes/pull/2021) +- Update table of contents navigation based on scroll position to indicate which link is currently active in the viewport. [#2020](https://github.com/mmistakes/minimal-mistakes/pull/2020) +- Clicking table of contents links changes URL has fragment. [#2019](https://github.com/mmistakes/minimal-mistakes/pull/2019) [#2023](https://github.com/mmistakes/minimal-mistakes/pull/2023) + +## [4.14.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.14.2) + +### Enhancements + +- Improve accessibility by adding label text to search button toggle. [#2014](https://github.com/mmistakes/minimal-mistakes/pull/2014) +- Update Lunr to 2.3.5. [#2010](https://github.com/mmistakes/minimal-mistakes/pull/2010) +- Shorten Internet Explorer conditional statement in `_includes/head.html`. [#2006](https://github.com/mmistakes/minimal-mistakes/pull/2006) +- Add Persian localized UI text strings. [#2004](https://github.com/mmistakes/minimal-mistakes/pull/2004) +- Remove unused JavaScript variables from Staticman comment script. [#1996](https://github.com/mmistakes/minimal-mistakes/pull/1996) +- Update Font Awesome to 5.6.0. [#1995](https://github.com/mmistakes/minimal-mistakes/pull/1995) +- Change remaining schema.org markup to `https`. [#1978](https://github.com/mmistakes/minimal-mistakes/pull/1978) +- Update NPM dependencies. + +### Bug Fixes + +- Fix wide tables that overflow parent container. [#2008](https://github.com/mmistakes/minimal-mistakes/issues/2008) +- Fix Spanish `comments_label` and `comments_title` UI text strings. [#1997](https://github.com/mmistakes/minimal-mistakes/pull/1997) +- Allow sidebar navigation with custom sidebar content. [#1986](https://github.com/mmistakes/minimal-mistakes/issues/1986) +- Fix Google Custom Search JavaScript error when not using Instant Search. [#1983](https://github.com/mmistakes/minimal-mistakes/pull/1983) + +## [4.14.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.14.1) + +### Bug Fixes + +- Fix closed navicon on hover. + +## [4.14.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.14.0) + +### Enhancements + +- Change schema.org markup to `https`. [#1969](https://github.com/mmistakes/minimal-mistakes/pull/1969) +- Add Google Drive as video provider. [#1967](https://github.com/mmistakes/minimal-mistakes/pull/1967) +- Match `:focus` color to skin. +- Add support for [utterances](https://utteranc.es/) comments. [#1909](https://github.com/mmistakes/minimal-mistakes/issues/1909) +- Use privacy aware embed options for YouTube and Vimeo in [responsive video helper](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#responsive-video-embed). [#1964](https://github.com/mmistakes/minimal-mistakes/pull/1964) +- Add `rel="nofollow noopener noreferrer"` to author profile links. [#1924](https://github.com/mmistakes/minimal-mistakes/pull/1924) +- Improve color contrast of primary buttons and links. +- Add Punjabi localized UI text strings. [#1962](https://github.com/mmistakes/minimal-mistakes/pull/1962) +- Add Hindi localized UI text strings. [#1888](https://github.com/mmistakes/minimal-mistakes/pull/1888) +- Update Lunr to `2.3.3`. [#1885](https://github.com/mmistakes/minimal-mistakes/pull/1885) +- Cache "static" includes to improve build performance. **Note:** The theme uses the [jekyll-include-cache](https://github.com/benbalter/jekyll-include-cache) plugin which will need to be installed in your `Gemfile` and added to the `plugins` array of `_config.yml`. Otherwise you'll throw `Unknown tag 'include_cached'` errors at build. [#1874](https://github.com/mmistakes/minimal-mistakes/pull/1874) +- Make entire feature and archive items "clickable". [#1864](https://github.com/mmistakes/minimal-mistakes/pull/1864) +- Allow custom Staticman endpoints. [#1842](https://github.com/mmistakes/minimal-mistakes/issues/1842) +- Remove `type="text/css"` from Algolia script includes. [#1836](https://github.com/mmistakes/minimal-mistakes/pull/1836) +- Remove unneeded `HandheldFriendly` and `MobileOptimized` meta tags. [#1837](https://github.com/mmistakes/minimal-mistakes/pull/1837) +- Update Font Awesome to version `5.5.0` and add `integrity` hash. [#1922](https://github.com/mmistakes/minimal-mistakes/pull/1922) +- Always load Google 404 Linkhelp script over HTTPS. [#1829](https://github.com/mmistakes/minimal-mistakes/pull/1829) +- Remove deprecated `base_path` include helper. + +### Bug Fixes + +- Prevent current post from showing in the related posts section. [#1976](https://github.com/mmistakes/minimal-mistakes/pull/1976) +- Fix dark skins syntax highlighting colors. [#1973](https://github.com/mmistakes/minimal-mistakes/issues/1973) +- Remove unnecessary closing bracket in analytics documentation. [#1915](https://github.com/mmistakes/minimal-mistakes/pull/1915) +- Fix breadcrumb navigation alignment. [#1917](https://github.com/mmistakes/minimal-mistakes/issues/1917) +- Fix Algolia search link positioning. [#1904](https://github.com/mmistakes/minimal-mistakes/pull/1904) +- Fix Lunr search index merging words. [#1883](https://github.com/mmistakes/minimal-mistakes/issues/1883) +- Properly apply `relative_url` filter to internal links in header overlay `actions` array. +- Revert cached includes (`include_cached`) for comment and analytics providers. [#1905](https://github.com/mmistakes/minimal-mistakes/issues/1905) + +## [4.13.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.13.0) + +### Enhancements + +- Add Romanian localized UI text strings. [#1814](https://github.com/mmistakes/minimal-mistakes/pull/1814) +- Improve author link flexibility. [#1581](https://github.com/mmistakes/minimal-mistakes/issues/1581) +- Improve footer link flexibility. +- Deprecate `cta_label` and `cta_url` in header overlay in favor of new `actions` array that allows for multiple "call to action" button links. [#1461](https://github.com/mmistakes/minimal-mistakes/issues/1461) +- Add support to [gallery helper](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#gallery) for defining column layout (`half`, `third`, or single `''`). [#1821](https://github.com/mmistakes/minimal-mistakes/issues/1821) + +### Bug Fixes + +- Fix sidebar navigation list toggle. [#1819](https://github.com/mmistakes/minimal-mistakes/issues/1819) +- Fix hover animation for links with `:visited` state. [#1820](https://github.com/mmistakes/minimal-mistakes/issues/1820) + +## [4.12.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.12.2) + +### Enhancements + +- Add missing Italian localized UI text strings. [#1793](https://github.com/mmistakes/minimal-mistakes/pull/1793) +- Update [jekyll-toc](https://github.com/allejo/jekyll-toc) to `v1.0.5`. +- Support heading levels 1-6 in table of contents with proper indentation styling. [#1782](https://github.com/mmistakes/minimal-mistakes/issues/1782) +- Use relative links for masthead navigation menu items when possible. [#1784](https://github.com/mmistakes/minimal-mistakes/pull/1784) +- Add `.emoji` class to author sidebar to normalize image sizes. [#1780](https://github.com/mmistakes/minimal-mistakes/pull/1780) +- Update Staticman commit message to include comment author's name. +- Improve side navigation spacing in relation to masthead. +- Style archive links with appropriate link color. +- Adjust feature row spacing and font-sizes. +- Use sentence case and increase font-sizes for improved readability in table of contents. +- Add {% raw %}`{{ content }}`{% endraw %} to `home` layout. [#1775](https://github.com/mmistakes/minimal-mistakes/pull/1775) + +## [4.12.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.12.1) + +### Enhancements + +- Add missing French localized UI text strings. [#1769](https://github.com/mmistakes/minimal-mistakes/pull/1769) [#1741](https://github.com/mmistakes/minimal-mistakes/pull/1741) +- Update Font Awesome to version [`5.2.0`](https://github.com/FortAwesome/Font-Awesome/blob/master/CHANGELOG.md). [#1754](https://github.com/mmistakes/minimal-mistakes/pull/1754) +- Add documentation note to update root `Gemfile` when forking theme. + +### Bug Fixes + +- Remove slash at the beginning of `path` in staticman.yml example. [#1772](https://github.com/mmistakes/minimal-mistakes/pull/1772) +- Fix `read_time` logic in header image overlay. [#1756](https://github.com/mmistakes/minimal-mistakes/pull/1756) + +## [4.12.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.12.0) + +### Enhancements + +- Add Hungarian localized UI text strings. [#1682](https://github.com/mmistakes/minimal-mistakes/pull/1682) +- DRY `tags_max` calculation in tags.html layout. [#1696](https://github.com/mmistakes/minimal-mistakes/pull/1696) +- DRY `categories_max` calculation in categories.html layout. +- Add support for ["sticking" table of contents](https://mmistakes.github.io/minimal-mistakes/layout-table-of-contents-sticky/) to top of page via `toc_sticky: true` YAML Front Matter. +- Add support for captioning images in feature row helper via `image_caption` YAML Front Matter. [#1440](https://github.com/mmistakes/minimal-mistakes/issues/1440) +- Add [Google Custom Search Engine](https://cse.google.com/cse) support. [#1652](https://github.com/mmistakes/minimal-mistakes/issues/1652) +- Update Font Awesome to version [`5.1.13`](https://github.com/FortAwesome/Font-Awesome/blob/master/CHANGELOG.md). +- Add "Pets" sample archive page to documentation site. [#1664](https://github.com/mmistakes/minimal-mistakes/pull/1664) +- Add GitLab social icon brand color. [#1653](https://github.com/mmistakes/minimal-mistakes/issues/1653) +- Prevent line breaks between FontAwesome icon and text in footer social links. [#1659](https://github.com/mmistakes/minimal-mistakes/issues/1659) + +### Bug Fixes + +- Set default `title_separator`. [#1701](https://github.com/mmistakes/minimal-mistakes/pull/1701) +- Fix `naver_site_verification` typo in /\_includes/seo.html. [#1687](https://github.com/mmistakes/minimal-mistakes/pull/1687) +- Fix table of contents missing borders. [#1675](https://github.com/mmistakes/minimal-mistakes/issues/1675) +- Fix link to "Recipes" sample archive on documentation site. [#1664](https://github.com/mmistakes/minimal-mistakes/pull/1664) +- Update example Reddit social share interpolation syntax in documentation. [#1656](https://github.com/mmistakes/minimal-mistakes/issues/1656) +- Fix "Back to Top" links on pages that use [header overlays](https://mmistakes.github.io/minimal-mistakes/docs/layouts/#header-overlay). + +## [4.11.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.11.2) + +### Enhancements + +- Update Font Awesome to version `5.0.11`. [#1605](https://github.com/mmistakes/minimal-mistakes/pull/1620) +- Add Slovak localized UI text strings. [#1613](https://github.com/mmistakes/minimal-mistakes/pull/1613) +- Add option to anonymize IP addresses of hits sent to Google Analytics. [#1636](https://github.com/mmistakes/minimal-mistakes/pull/1636) + +### Bug Fixes + +- Use correct text string for "Back to Top" link. [#1595](https://github.com/mmistakes/minimal-mistakes/issues/1595) +- Add conditionals for showing `reCaptcha.siteKey` and `reCaptcha.secret` in Staticman comments form. + +## [4.11.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.11.1) + +### Enhancements + +- Add default `theme` and `remote_theme` values to `_config.yml`. +- Add new layouts (`posts`, `categories`, `tags`, `collection`, `category`, and `tag`) for easier archive page creation. + +### Bug Fixes + +- Replace `relative_url` filter with `relative_url` where it makes sense (asset/navigation related paths). [#1588](https://github.com/mmistakes/minimal-mistakes/issues/1588) +- Fix search excerpts that run together because of implied spaces. + +## [4.10.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.10.1) + +### Enhancements + +- Update jQuery to version `3.3.1`. [#1491](https://github.com/mmistakes/minimal-mistakes/issues/1491) +- Add link to jekyll-algolia's `files_to_exclude` documentation. +- Update Font Awesome to version [`5.0.8`](https://github.com/FortAwesome/Font-Awesome/blob/master/CHANGELOG.md). [#1561](https://github.com/mmistakes/minimal-mistakes/pull/1561) +- Activate Algolia search for documentation site. [#1570](https://github.com/mmistakes/minimal-mistakes/issues/1570) +- Add missing German translations. [#1577](https://github.com/mmistakes/minimal-mistakes/pull/1577) +- Add support for Google Analytics with global site tag (gtag.js) [#1563](https://github.com/mmistakes/minimal-mistakes/pull/1563) + +### Bug Fixes + +- Focus Algolia search input after clicking on search toggle. + +## [4.10.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.10.0) + +### Enhancements + +- Add support for [Algolia](https://www.algolia.com/) search provider ([see demo](https://mmistakes.github.io/minimal-mistakes-algolia-search/)). [#1416](https://github.com/mmistakes/minimal-mistakes/issues/1416) + +## [4.9.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.9.1) + +### Enhancements + +- Simplify year archive Liquid. +- Add documentation on how to downgrade theme. +- Improve greedy navigation's layout when JavaScript is disabled. +- Improve SEO include by grouping similar tags, reducing white-space, and adding `article:modified_time`. [#1456](https://github.com/mmistakes/minimal-mistakes/pull/1456) +- Minify `assets/js/lunr/lunr.js`. +- Improve calculation of Greedy navigation's `availableSpace`. +- Add Danish and Russian translations for new search strings. [#1472](https://github.com/mmistakes/minimal-mistakes/pull/1472) [#1477](https://github.com/mmistakes/minimal-mistakes/pull/1477) +- Indicate that archive titles are links with an underline. +- Remove `base_path` include from `/test` pages. +- Reduce font-size of page meta in list/grid items. +- Improve feature row styling when used with `archive` layout. [#1484](https://github.com/mmistakes/minimal-mistakes/issues/1484) +- Improve German translations. [#1511](https://github.com/mmistakes/minimal-mistakes/pull/1511) +- Update Font Awesome to `5.0.6`. [#1513](https://github.com/mmistakes/minimal-mistakes/pull/1513) +- Add `wide` variant to single layout. [#1516](https://github.com/mmistakes/minimal-mistakes/pull/1516) + +### Bug Fixes + +- Allow `author` to accept an object or string. [#289](https://github.com/mmistakes/minimal-mistakes/issues/289) +- Fix syntax highlighting line number styling inconsistency. [#1467](https://github.com/mmistakes/minimal-mistakes/issues/1467) +- Fix author sidebar icon colors for dark skins. [#1482](https://github.com/mmistakes/minimal-mistakes/issues/1482) +- Remove misleading underline hover state on feature row items. +- Properly escape quotes in `site.social.name` and `site.name`. [#1485](https://github.com/mmistakes/minimal-mistakes/pull/1485) +- Fix typo in upgrading documentation. [#1487](https://github.com/mmistakes/minimal-mistakes/pull/1487) +- Fix `border-bottom` for Gist line numbers. +- Replace `|` with HTML entity when used as title separator. [#760](https://github.com/mmistakes/minimal-mistakes/issues/760) + +## [4.9.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.9.0) + +### Enhancements + +- Add `show_overlay_excerpt` for disabling overlay image excerpt text. [#1436](https://github.com/mmistakes/minimal-mistakes/pull/1436) +- Update remote theme installation instructions in Quick Start Guide. [#1439](https://github.com/mmistakes/minimal-mistakes/pull/1439) +- Reduce visual weight of code blocks. +- Add Lunr.js Greek stemmer. [#1445](https://github.com/mmistakes/minimal-mistakes/pull/1445) +- Update Font Awesome 5 [SVG with JavaScript version](https://fontawesome.com/how-to-use/svg-with-js). [#1446](https://github.com/mmistakes/minimal-mistakes/pull/1446) + - Note: if Font Awesome icons were used in the content of posts/pages or custom table of contents, find and replace any icons that have different names between version 4 and 5. Make sure to read the [complete list](https://fontawesome.com/how-to-use/upgrading-from-4#icon-name-changes-full) on Font Awesome's site. +- Reduce size of Lunr.js search JSON data and introduce `site.search_full_content` flag for limiting size of JSON file. [#1449](https://github.com/mmistakes/minimal-mistakes/pull/1449) +- Improve syntax highlighting styles. [#1450](https://github.com/mmistakes/minimal-mistakes/pull/1450) + +### Bug Fixes + +- Fix code block extra white-space when using [Jekyll's highlight tag](https://jekyllrb.com/docs/templates/#code-snippet-highlighting) with `linenos`. [#1437](https://github.com/mmistakes/minimal-mistakes/issues/1437) +- Round top-right corner of code block icon. +- Remove Lunr.js trimmer and bring back colons. [#1445](https://github.com/mmistakes/minimal-mistakes/pull/1445) +- Fix sticky `.sidebar` that overlaps main content when resizing viewport. [#1447](https://github.com/mmistakes/minimal-mistakes/issues/1447) + +## [4.8.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.8.1) + +### Enhancements + +- Add linkback functionality to author avatar and name in sidebar via `author.home`. [#1386](https://github.com/mmistakes/minimal-mistakes/pull/1386) +- Add Japanese localized UI text strings. [#1411](https://github.com/mmistakes/minimal-mistakes/pull/1411) +- Update Lunr.js to 2.1.5 [#1419](https://github.com/mmistakes/minimal-mistakes/pull/1419) + +### Bug Fixes + +- Fixed broken link to Staticman's page [#1422](https://github.com/mmistakes/minimal-mistakes/pull/1422) +- Fix Lunr search to work with number tags. [#1409](https://github.com/mmistakes/minimal-mistakes/issues/1409) [#1419](https://github.com/mmistakes/minimal-mistakes/pull/1419) + +## [4.8.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.8.0) + +### Enhancements + +- Open social share links in a new window. [#1357](https://github.com/mmistakes/minimal-mistakes/pull/1357) +- Remove Alexa.com verification due to retiring of "[Claim Your Site](https://support.alexa.com/hc/en-us/articles/219135887)" feature. [#1350](https://github.com/mmistakes/minimal-mistakes/issues/1350) +- Disable analytics in `development` environment. [#1362](https://github.com/mmistakes/minimal-mistakes/pull/1362) +- Disable comments in `development` environment. [#1363](https://github.com/mmistakes/minimal-mistakes/pull/1363) +- Exclude specific pages/posts from search index by adding `search: false` to the YAML Front Matter. [#1369](https://github.com/mmistakes/minimal-mistakes/pull/1369) +- Add optional `description` key to masthead links for clarifying their purpose with the `title` attribute. [#1380](https://github.com/mmistakes/minimal-mistakes/pull/1380) +- Incorporate site search into masthead. [#1383](https://github.com/mmistakes/minimal-mistakes/pull/1383) +- Update gem dependencies. [#1388](https://github.com/mmistakes/minimal-mistakes/pull/1388) + +### Bug Fixes + +- Fix `post.content` typo in `assets/js/lunr-en.js`. [#1354](https://github.com/mmistakes/minimal-mistakes/pull/1354) +- Fix "lunr-en.js:1 Uncaught SyntaxError: Unexpected token <" in `assets/js/lunr-en.js`. [#1356](https://github.com/mmistakes/minimal-mistakes/pull/1356) +- Rename Naver verification `naver_site_verification` to be consistent with other site variables. +- Fix button class in "Post with Table Of Contents" demo content. [#1368](https://github.com/mmistakes/minimal-mistakes/pull/1368) +- Fix capitalization of WordPress in documentation. [#1381](https://github.com/mmistakes/minimal-mistakes/pull/1381) +- Fix zh-HK UI text to point to Traditional Chinese. [#1374](https://github.com/mmistakes/minimal-mistakes/issues/1374) [#1389](https://github.com/mmistakes/minimal-mistakes/pull/1389) + +## [4.7.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.7.1) + +### Enhancements + +- Add search layout powered by [Lunr](https://lunrjs.com/). [#1353](https://github.com/mmistakes/minimal-mistakes/pull/1353) +- Use [jekyll-remote-theme](https://github.com/benbalter/jekyll-remote-theme) for demo site. [#1339](https://github.com/mmistakes/minimal-mistakes/issues/1339) +- Add note about WordPress to Staticman comment migration tool in documentation. [#1346](https://github.com/mmistakes/minimal-mistakes/issues/1346) + +### Bug Fixes + +- Change `http` to `https` for Jekyll and Browserhappy links. [#1342](https://github.com/mmistakes/minimal-mistakes/pull/1342) [#1343](https://github.com/mmistakes/minimal-mistakes/pull/1343) +- Change `http` author profile links to `https` when supported. [#1349](https://github.com/mmistakes/minimal-mistakes/pull/1349) +- Fix broken SCSS partial links in layouts documentation. [#1351](https://github.com/mmistakes/minimal-mistakes/issues/1351) + +## [4.7.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.7.0) + +### Enhancements + +- Add `alt` description to avatar image. [#1226](https://github.com/mmistakes/minimal-mistakes/pull/1226) +- Clarify documentation about which `assets` folders and files to remove when migrating to the gem version of the theme. [#1268](https://github.com/mmistakes/minimal-mistakes/issues/1268) +- Add note about Staticman GitHub compatibility. [#1273](https://github.com/mmistakes/minimal-mistakes/issues/1273) +- Add missing Brazilian Portuguese translations to `ui-text.yml`. [#1278](https://github.com/mmistakes/minimal-mistakes/pull/1278) +- Update font stack documentation. [#1292](https://github.com/mmistakes/minimal-mistakes/pull/1292) +- Improve accessibility of navigation menu button. [#1099](https://github.com/mmistakes/minimal-mistakes/issues/1099) +- Add Naver Webmaster Tools verification. [#1286](https://github.com/mmistakes/minimal-mistakes/pull/1286) +- Add support for Staticman v2 endpoint and reCAPTCHA. +- Add Polish localized UI text strings. [#1304](https://github.com/mmistakes/minimal-mistakes/pull/1304) +- Add toggleable table of contents via YAML Front Matter. Note: `toc` helper include will be deprecated in next major version. [#1222](https://github.com/mmistakes/minimal-mistakes/issues/1222) +- Refactor seo.html include to DRY-up page image handling. +- Add support for setting what image is used by OpenGraph and Twitter via `page.header.og_image`. [#1316](https://github.com/mmistakes/minimal-mistakes/issues/1316) +- Fix the spelling of some product names in the author profile. [#1328](https://github.com/mmistakes/minimal-mistakes/pull/1328) +- Add `aqua`, `neon`, and `plum` skins. [#1336](https://github.com/mmistakes/minimal-mistakes/pull/1336) +- Update **jekyll-toc** with heading classes fix. [#1337](https://github.com/mmistakes/minimal-mistakes/pull/1337) +- Remove `+` from Google+ author link to allow non-vanity URLs. [#1319](https://github.com/mmistakes/minimal-mistakes/pull/1319) + +### Bug Fixes + +- Fix system font rendering in Chrome on macOS/OS X. [#1290](https://github.com/mmistakes/minimal-mistakes/pull/1290) +- Fix extra padding in syntax highlighted code blocks due to Rouge 2 adding `<div class="highlight"></div>` to markup. + +## [4.6.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.6.0) + +### Enhancements + +- Test strict Front Matter in `/test` site. [#1236](https://github.com/mmistakes/minimal-mistakes/pull/1236) +- Rename `gems` key to `plugins`. [#1239](https://github.com/mmistakes/minimal-mistakes/pull/1239) +- Add [YIQ Color Contrast](https://github.com/easy-designs/yiq-color-contrast) mixin for determining lightness of a color. +- DRY up button CSS using Sass lists and YIQ Color Contrast mixin. +- Add `btn--primary` button class. **Note:** elements that were previously using only a `.btn` class will now also need `.btn--primary` (eg. `<a class="btn btn--primary" href="#">my link</a>`). +- Add `air`, `contrast`, `dark`, `dirt`, `mint`, and `sunrise` skin color options. [#1208](https://github.com/mmistakes/minimal-mistakes/issues/1208) +- Allow scripts in `<head>` and before `</body>` to be added/overridden with `head_scripts` and `footer_scripts` arrays in `_config.yml`. [#1241](https://github.com/mmistakes/minimal-mistakes/pull/1241) +- Update JavaScript dependencies: jQuery `v3.2.1`, jQuery Smooth Scroll `v2.2.0`, and Magnific Popup `v1.1.0`. [#328690652](https://github.com/mmistakes/minimal-mistakes/pull/1241#issuecomment-328690652) + +## [4.5.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.5.2) + +### Enhancements + +- Add `.page__comments-form` to "non-printing" selectors in print styles. [#1195](https://github.com/mmistakes/minimal-mistakes/pull/1195) +- Add LinkedIn and Steam author sidebar examples to `_config.yml`. [#1203](https://github.com/mmistakes/minimal-mistakes/pull/1203) [#1204](https://github.com/mmistakes/minimal-mistakes/pull/1204) +- Remove the http-equiv="cleartype" meta tag. [#1087](https://github.com/mmistakes/minimal-mistakes/pull/1087) +- Clarify documentation for `jekyll-archives` plugin and how to install. [#1206](https://github.com/mmistakes/minimal-mistakes/pull/1206) +- Clarify documentation around taxonomy page and index generation. [#1207](https://github.com/mmistakes/minimal-mistakes/pull/1207) +- Fix "Posts by tag" grammar in documentation. [#1209](https://github.com/mmistakes/minimal-mistakes/pull/1209) +- Improve Chinese `date_label` and `minute_read` translations in `ui-text.yml`. [#1205](https://github.com/mmistakes/minimal-mistakes/pull/1205) [#1211](https://github.com/mmistakes/minimal-mistakes/pull/1211) +- Add note to Quick-Start Guide about GitHub Pages hosting alternatives that allow 3rd party gem themes and Jekyll plugins. +- Add note to configuration documentation about Cloudflare minification as an alternative to `layout: compress`. [#1217](https://github.com/mmistakes/minimal-mistakes/pull/1217) +- Show 4 latest posts in "You May Also Enjoy" module when `related: true` and no related posts are found due to `lsi` ([latent semantic indexing](https://en.wikipedia.org/wiki/Latent_semantic_analysis#Latent_semantic_indexing)) being disabled on GitHub Pages. [#554](https://github.com/mmistakes/minimal-mistakes/issues/554) +- Truncate archive item titles' that overflow with an ellipsis. [#1213](https://github.com/mmistakes/minimal-mistakes/issues/1213) + +### Bug Fixes + +- Fix license URL in README file. [#1189](https://github.com/mmistakes/minimal-mistakes/pull/1189) +- Reduce amount of blank pages when printing in Chrome. [#1196](https://github.com/mmistakes/minimal-mistakes/issues/1196) +- Remove `#disqus_thread` duplicate from `comments-providers/disqus.html` as it is already in `comments.html` include. [#1199](https://github.com/mmistakes/minimal-mistakes/issues/1199) +- Fix Liquid syntax errors in `tag-list.html` and `category-list.html` includes by removing parenthesis in `assign`s. [#1223](https://github.com/mmistakes/minimal-mistakes/issues/1223) +- Fix Liquid syntax error: "Expected id but found open_square in {% raw %}`"{{ page.[include.id] }}"`"{% endraw %} in `gallery` and `feature_row` includes. +- Fix Liquid syntax error: "Expected end_of_string but found pipe in `"name in __names | sort"`" in `group-by-array` include. + +## [4.5.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.5.1) + +### Enhancements + +- Add Greek and Danish localized UI text strings. [#1159](https://github.com/mmistakes/minimal-mistakes/pull/1159) [#1188](https://github.com/mmistakes/minimal-mistakes/pull/1188) +- Remove blank YAML Front Matter from JavaScript banner. [#1158](https://github.com/mmistakes/minimal-mistakes/issues/1158) +- Improve `page` and `archive` layouts to visually center main content and harmonize sidebar widths and placement. [#1166](https://github.com/mmistakes/minimal-mistakes/pull/1166) +- Increase font-size of code blocks. +- Reduce indent of nested "table of contents" links. +- Extend [archive grid view](https://mmistakes.github.io/minimal-mistakes/docs/layouts/) to the right to better fill the page. +- URL encode title and page URL in social share links. [#1177](https://github.com/mmistakes/minimal-mistakes/pull/1177) +- Replace old Disqus script with new Universal Embed Code. [#1179](https://github.com/mmistakes/minimal-mistakes/pull/1179) + +### Bug Fixes + +- Fix positioning of sidebar table of contents when using `layout: splash`. [#1169](https://github.com/mmistakes/minimal-mistakes/issues/1169) +- Fix "follow" links `z-index` order to avoid overlapping issues. [#1167](https://github.com/mmistakes/minimal-mistakes/issues/1167) + +### Maintenance + +- Fix typo `words_per_minute` typo in documentation. [#1164](https://github.com/mmistakes/minimal-mistakes/pull/1164) +- Remove outside and right borders in `table`s. +- Adjust width of `.sidebar` to match `.sidebar__right`. +- Add sample documents to ["portfolio" collection](https://mmistakes.github.io/minimal-mistakes/portfolio/) for testing grid view. +- Fix typo in stylesheets documentation. [#1170](https://github.com/mmistakes/minimal-mistakes/pull/1170) +- Add note about setting Discourse `server` as a scheme-less URL (eg. `meta.discourse.com` and not `http://meta.discourse.com`) in `_config.yml`. [#1182](https://github.com/mmistakes/minimal-mistakes/issues/1182) + +## [4.5.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.5.0) + +### Enhancements + +- Add scrollbar to sidebars with overflowing content that extends outside the viewport's height. [#706](https://github.com/mmistakes/minimal-mistakes/issues/706) +- Add missing Spanish UI text strings. [#1118](https://github.com/mmistakes/minimal-mistakes/pull/1118) +- Update Susy to version 3 and rewrite grid CSS to be more readable. +- Refactor intro animations into a separate Sass variable `$intro-transition` to allow for customizing. [#1147](https://github.com/mmistakes/minimal-mistakes/pull/1147) +- Add [**jekyll-data**](https://github.com/ashmaroli/jekyll-data) as a dependency to read data files from theme-gem. [#1131](https://github.com/mmistakes/minimal-mistakes/pull/1131) +- Add support for customizing header image alternative text through YAML Front Matter. [#1138](https://github.com/mmistakes/minimal-mistakes/pull/1138) + +### Bug Fixes + +- Fix Sass `DEPRECATION WARNING: Passing a string to call()` by [upgrading Susy to version 3](https://github.com/mmistakes/minimal-mistakes/commit/387f8149d6270b876f224a57a07062ffb0647938). [#1114](https://github.com/mmistakes/minimal-mistakes/issues/1114) +- Fix disappearing author profile links due to tapping the "Follow" button and changing a browser's viewport width to > `$lg`. [#1136](https://github.com/mmistakes/minimal-mistakes/issues/1136) + +### Maintenance + +- Replace reference to "Basically Basic theme" with **Minimal Mistakes**. [#1149](https://github.com/mmistakes/minimal-mistakes/pull/1149) +- Add documentation for disabling CSS3 animations. [#1150](https://github.com/mmistakes/minimal-mistakes/pull/1150) +- Update quickstart, installation, and overriding defaults documentation. [#1151](https://github.com/mmistakes/minimal-mistakes/pull/1151) + +## [4.4.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.4.2) + +### Enhancements + +- Add Swedish, Dutch, and Indonesian localized UI text strings. [#996](https://github.com/mmistakes/minimal-mistakes/pull/996) [#1081](https://github.com/mmistakes/minimal-mistakes/pull/1081) [#1101](https://github.com/mmistakes/minimal-mistakes/pull/1101) +- Add Bitbucket social icon color. [#1009](https://github.com/mmistakes/minimal-mistakes/pull/1009) +- Add GitLab to author sidebar. [#1050](https://github.com/mmistakes/minimal-mistakes/pull/1050) +- Add Sass variable for navicon link hover color. [#1089](https://github.com/mmistakes/minimal-mistakes/pull/1089) [#1088](https://github.com/mmistakes/minimal-mistakes/pull/1088) + +### Bug Fixes + +- Toggle close button on `mouseleave`. [#975](https://github.com/mmistakes/minimal-mistakes/issues/975) +- Remove extraneous `</a>` and `</li>` tags from `paginator.html` include. [#1038](https://github.com/mmistakes/minimal-mistakes/pull/1038) +- Fix Google+ comments provider includes. [#1092](https://github.com/mmistakes/minimal-mistakes/issues/1092) +- Replace category variable used in `_includes/breadcrumbs.html` to `site.category_archive` to avoid conflicts with `site.categories`. [#1063](https://github.com/mmistakes/minimal-mistakes/pull/1063) [#329](https://github.com/mmistakes/minimal-mistakes/issues/329) + +### Maintenance + +- Add mention of Greek localized UI text strings to theme documentation. [#972](https://github.com/mmistakes/minimal-mistakes/pull/972) +- Update Greek localized UI text strings. [#1054](https://github.com/mmistakes/minimal-mistakes/pull/1054) +- Add documentation for adding teaser images in grid view using `header.teaser`. + +## [4.4.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.4.1) + +### Enhancements + +- Add Greek localized UI text strings. [#958](https://github.com/mmistakes/minimal-mistakes/pull/958) + +### Bug Fixes + +- Fix `video` helper to load Vimeo videos over https. [#945](https://github.com/mmistakes/minimal-mistakes/pull/945) +- Fix close menu button that was removed when updating Greedy navigation script. [#969](https://github.com/mmistakes/minimal-mistakes/issues/969) + +## [4.4.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.4.0) + +### Enhancements + +- Move SCSS partials to `/_sass/minimal-mistakes` for easier CSS customization. +- Replace `modified` with `last_modified_at` to leverage various Jekyll plugins that utilize this variable. [#930](https://github.com/mmistakes/minimal-mistakes/pull/930) +- Add Lithuanian localized UI text. [#924](https://github.com/mmistakes/minimal-mistakes/pull/924) +- Improve print stylesheet by increasing text contrast, removing elements that don't need to be printed, expanding URLs, and reducing amount of blank pages. [#909](https://github.com/mmistakes/minimal-mistakes/issues/909) + +### Maintenance + +- Remove extra word in comment. [#911](https://github.com/mmistakes/minimal-mistakes/pull/911) +- Fix typo in Utility Class docs. [#915](https://github.com/mmistakes/minimal-mistakes/pull/915) + +## [4.3.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.3.1) + +### Bug Fixes + +- Fix `.masthead` and `.page__footer` overlapping full screen video elements. [#933](https://github.com/mmistakes/minimal-mistakes/issues/933) +- Correctly show Related Posts heading when UI Text data file is omitted and `related: true` in YAML Front Matter. [#901](https://github.com/mmistakes/minimal-mistakes/pull/901) + +## [4.3.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.3.0) + +### Enhancements + +- Add workaround to allow theme gem's `/assets/js/main.min.js` file to be overridden by a local version. Simply add the following YAML Front Matter to the file: + + ``` + --- + layout: + --- + ``` + + Any local customizations you make to `/assets/js/main.min.js` should now replace the theme gem's version. + +## [4.2.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.2.2) + +### Enhancements + +- Update [Greedy Navigation](https://github.com/lukejacksonn/GreedyNav) to flexbox version to make it more flexible when dealing with long site titles (`site.title`). [#836](https://github.com/mmistakes/minimal-mistakes/issues/836) +- Adjust `box-shadow` in navigation and author sidebar. [#576](https://github.com/mmistakes/minimal-mistakes/pull/576) +- Add Russian, Korean, and zh-TW localized UI text. [#815](https://github.com/mmistakes/minimal-mistakes/issues/815) [#834](https://github.com/mmistakes/minimal-mistakes/pull/834) [#838](https://github.com/mmistakes/minimal-mistakes/pull/838) + +### Bug Fixes + +- Fix Discourse embedded comments bug. [#823](https://github.com/mmistakes/minimal-mistakes/issues/823) +- Fix `seo_author` default value in `seo.html` and add `author` meta. [#858](https://github.com/mmistakes/minimal-mistakes/pull/858) + +### Maintenance + +- Add theme meta info to `_layouts/default.html` and `main.css`. +- Update README. +- Improve the pagination and taxonomy archive documentation. [#826](https://github.com/mmistakes/minimal-mistakes/pull/826) +- Add comments to `/docs/_config.yml` to clarify use of YAML references. [#847](https://github.com/mmistakes/minimal-mistakes/pull/847) + +## [4.2.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.2.1) + +### Enhancements + +- Improve `paginator.html` to support paginated pages that live inside of a subfolder. See [documentation](https://mmistakes.github.io/minimal-mistakes/docs/layouts/#home-page) for more details. [#764](https://github.com/mmistakes/minimal-mistakes/pull/764/) + +### Maintenance + +- Add `https` protocol to Google Universal Analytics embed. [#772](https://github.com/mmistakes/minimal-mistakes/pull/772) + +## [4.2.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.2.0) + +### Enhancements + +- Add `video` helper (for YouTube/Vimeo) and video headers to `single`, `archive`, and `splash` layouts. [#788](https://github.com/mmistakes/minimal-mistakes/pull/788) +- Add missing simplified Chinese localized UI text strings. [#747](https://github.com/mmistakes/minimal-mistakes/pull/747) +- Add Nepali (Nepalese) localized UI text strings. [#785](https://github.com/mmistakes/minimal-mistakes/pull/785) +- Remove borders from table elements found in Google Custom Search Engine widget. [#759](https://github.com/mmistakes/minimal-mistakes/issues/759) + +### Bug Fixes + +- Remove `position: sticky` JavaScript polyfill and fallback to default positioning for browsers that don't support it. [#752](https://github.com/mmistakes/minimal-mistakes/issues/752) + +### Maintenance + +- Fix invalid Google Universal Analytics example in documentation. [#783](https://github.com/mmistakes/minimal-mistakes/pull/783) +- Bump `jekyll-sitemap` gem dependency to (1.0). + +## [4.1.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.1.1) + +### Enhancements + +- Remove hardcoded `words_per_minute` "less than" and "minute read" values and make dynamic. [#703](https://github.com/mmistakes/minimal-mistakes/issues/703) +- Update Font Awesome to `v4.7.0`. [#723](https://github.com/mmistakes/minimal-mistakes/issues/723), [#722](https://github.com/mmistakes/minimal-mistakes/issues/722) +- Add support for YouTube channel URLs in author profile. [#716](https://github.com/mmistakes/minimal-mistakes/issues/716) + +### Bug Fixes + +- Add Jekyll as `spec.add_runtime_dependency` in `.gemspec`. + +## [4.1.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.1.0) + +### Enhancements + +- Add Jekyll include for adding [custom author profile links](https://github.com/mmistakes/minimal-mistakes/blob/master/_includes/author-profile-custom-links.html) to sidebar + +### Bug Fixes + +- Fix link to Discourse.org homepage in `noscript` section [#699](https://github.com/mmistakes/minimal-mistakes/pull/699) +- Fix padding issue with pagination buttons [#694](https://github.com/mmistakes/minimal-mistakes/issues/694) + +## [4.0.10](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.0.10) + +### Bug Fixes + +- Add Staticman default `path`. [#683](https://github.com/mmistakes/minimal-mistakes/issues/683) + +### Maintenance + +- Slight correction/improvements to French UI text. [#685](https://github.com/mmistakes/minimal-mistakes/pull/685) + +## [4.0.9](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.0.9) + +### Bug Fixes + +- Fix overlapping sidebar navigation lists due to `max-height: 100vh`. [#668](https://github.com/mmistakes/minimal-mistakes/issues/668) + +## [4.0.8](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.0.8) + +### Bug Fixes + +- Set default value for `words_per_minute`. [#657](https://github.com/mmistakes/minimal-mistakes/issues/657) +- Adjust sidebar navigation list CSS so it collapses at the correct width. + +### Maintenance + +- Add Google AdSense banner to `/docs/_layouts/default.html` for demo site. + +## [4.0.7](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.0.7) + +### Enhancements + +- Add `!default` values to **\_sass/\_variables.scss**. +- Collapse sidebar navigation lists on smaller screens. [#607](https://github.com/mmistakes/minimal-mistakes/issues/607) + +### Bug Fixes + +- Rename `#comments` to something more unique to avoid clashes with Kramdown generated headline IDs. [#582](https://github.com/mmistakes/minimal-mistakes/issues/582) + +### Maintenance + +- Reorganize SCSS partials in **assets/css/main.scss** + +## [4.0.6](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.0.6) + +### Enhancements + +- Add [`figure` helper](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#figure) to make generating a `<figure>` element with a single image and caption easier. [#572](https://github.com/mmistakes/minimal-mistakes/pull/572) +- Add structured data markup for `itemprop="person"` in author profile sidebar. [#647](https://github.com/mmistakes/minimal-mistakes/pull/647) + +### Bug Fixes + +- Fix improper YAML formatting of some locales. [#651](https://github.com/mmistakes/minimal-mistakes/pull/651) + +### Maintenance + +- Clarify "migrating to gem-theme" instructions in **Quick Start Guide**. +- Add `rake preview` task for testing `/test` during theme development. + +## [4.0.5](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.0.5) + +### Enhancements + +- Update gems: `jekyll-sitemap` (0.12), `jekyll-feed` (0.8). +- Improve next/previous pager links visibility by changing gray color to blue (`$link-color`). + +### Bug Fixes + +- Fix `.sidebar` flicker/jump when hovered. [#583](https://github.com/mmistakes/minimal-mistakes/issues/583) + +### Maintenance + +- Move contents of `gh-pages` branch to `master` inside of the `/docs` folder. + +## [4.0.4](https://github.com/mmistakes/minimal-mistakes/releases/tag/4.0.4) + +### Enhancements + +- "Gemify" theme ~> `gem "minimal-mistakes-jekyll"` +- Replace `base_path` include with `relative_url` filter where possible. +- Allow images to be placed in other folders. Remove `/images/` only restriction and encourage placement in `/assets/images/` instead. **Full paths are now required. If upgrading from MM 3.4 add `/images/` before filenames in Front Matter and `_config.yml` variables.** +- Add [home `layout`](https://github.com/mmistakes/minimal-mistakes/blob/master/_layouts/home.html) +- Added missing Turkish translations for UI text. [#621](https://github.com/mmistakes/minimal-mistakes/pull/621) +- Make author avatar optional in sidebar. +- Update **/\_includes/seo.html** for meta description. [#558](https://github.com/mmistakes/minimal-mistakes/pull/558) + +### Bug Fixes + +- Fix navigation bar animation "flicker" in Safari [#568](https://github.com/mmistakes/minimal-mistakes/issues/568) +- Fix `author.avatar` paths for externally hosted images. + +### Maintenance + +- Add documentation around `gem "minimal-mistakes-jekyll"` installation and use. +- Add note about using full image paths for eg. `assets/images/filename.jpg` (header images, overlays, galleries, feature rows, etc.) instead of assuming they will always be in `/images/`. +- Add "[Overriding Theme Defaults](https://mmistakes.github.io/minimal-mistakes/docs/overriding-theme-defaults/)" page to documentation. + +## [3.4.8](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.4.8) + +### Enhancements + +- Improve type readability for larger viewports by bumping up base `font-size`. [#533](https://github.com/mmistakes/minimal-mistakes/issues/533) +- Update Portuguese localized UI text. [#541](https://github.com/mmistakes/minimal-mistakes/pull/541) +- Add `page.title` and via parameter to Twitter share link. [#538](https://github.com/mmistakes/minimal-mistakes/pull/538) + +### Bug Fixes + +- Fix Last.fm author profile URL. [#540](https://github.com/mmistakes/minimal-mistakes/pull/540) + +### Maintenance + +- Move Brazilian Portuguese localized text under `pt-BR` key. + +## [3.4.7](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.4.7) + +### Enhancements + +- Add `layout` based and user-defined class names to `<body>` element for added CSS hooks. [#526](https://github.com/mmistakes/minimal-mistakes/pull/526) +- Add simplified Chinese localized UI text. [#532](https://github.com/mmistakes/minimal-mistakes/pull/532) + +### Bug Fixes + +- Remove duplicate include of `base_path` in category-list.html [#522](https://github.com/mmistakes/minimal-mistakes/pull/522) + +## [3.4.6](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.4.6) + +### Enhancements + +- Add Italian "comments" related localized UI text. [#514](https://github.com/mmistakes/minimal-mistakes/pull/514) + +### Bug Fixes + +- Disable `compress` HTML layout by default. To enable add `layout: compress` to `_layouts/default.html`. + +## [3.4.5](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.4.5) + +### Enhancements + +- Improve line numbered code block styling when using `{% raw %}{% highlight linenos %}{% endraw %}` tag. [#513](https://github.com/mmistakes/minimal-mistakes/issues/513) +- Add English fallback to "Follow" button label. [#496](https://github.com/mmistakes/minimal-mistakes/pull/496) + +### Bug Fixes + +- Fix Firefox alignment issues with code blocks generated with the `{% raw %}{% highlight %}{% endraw %}` tag. [#512](https://github.com/mmistakes/minimal-mistakes/issues/512) + +### Maintenance + +- Clarified comment for `author.stackoverflow` value used in author sidebar links. [#487](https://github.com/mmistakes/minimal-mistakes/pull/487) +- Add list of localized text strings. [#488](https://github.com/mmistakes/minimal-mistakes/pull/488) +- Add `{% raw %}{% highlight %}{% endraw %}` code block examples to demo site. +- Add documentation for using custom sidebar navigation menus. [#476](https://github.com/mmistakes/minimal-mistakes/issues/476) + +## [3.4.4](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.4.4) + +### Enhancements + +- Add French "comments" related localized UI text. [#472](https://github.com/mmistakes/minimal-mistakes/pull/472) + +### Bug Fixes + +- Exclude `vendor` in Jekyll config file. +- Fix Liquid syntax error for offending parenthesis. [#479](https://github.com/mmistakes/minimal-mistakes/issues/479) + +### Maintenance + +- Update gems: `colorator` (1.1.0), `forwardable-extended` (2.6.0), `github-pages` (93), `jekyll` (= 3.2.1), `minima` (= 1.0.1). + +## [3.4.3](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.4.3) + +### Enhancements + +- Make ["honeypot" `input`](https://github.com/mmistakes/minimal-mistakes/commit/06a8249a69a37dddda7e2a5bfbe32056c1a9a607) in Staticman comment form less obvious to spam bots +- Add padding to `.highlight` code blocks to better [align `overflow` scrollbar](https://github.com/mmistakes/minimal-mistakes/commit/e4abec0a6f7f8cff72505ca0754615df294fd5b3) to the bottom. +- Add additional image options for Twitter card social sharing meta tags. [#466](https://github.com/mmistakes/minimal-mistakes/pull/466) +- Add structured data markup for Staticman comments. [#458](https://github.com/mmistakes/minimal-mistakes/issues/458) + +### Bug Fixes + +- Format `og:locale` tag with `_` instead of `-`. [#462](https://github.com/mmistakes/minimal-mistakes/issues/462) + +### Maintenance + +- Add note to docs about using `url: http://localhost:4000` when working locally. + +## [3.4.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.4.2) + +### Enhancements + +- Improve UX of static comment forms. [#448](https://github.com/mmistakes/minimal-mistakes/issues/448) + +## [3.4.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.4.1) + +### Enhancements + +- Add `staticman.filename` configuration with UNIX timestamp for sorting data files. example ~> `comment-1470943149`. + +### Bug Fixes + +- Don't add `<a>` to author name if URL is blank. + +## [3.4.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.4.0) + +### Enhancements + +- Support static-based commenting via [Staticman](https://staticman.net/) for sites hosted with GitHub Pages. [#424](https://github.com/mmistakes/minimal-mistakes/issues/424) + +## [3.3.7](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.3.7) + +### Bug Fixes + +- Re-enabled Jekyll plugins in `_config.yml` in case they aren't autoloaded in `Gemfile`. [#417](https://github.com/mmistakes/minimal-mistakes/issues/417) + +### Enhancements + +- Fallback to `site.github.url` for use in `{{ base_path }}` when `site.url` is `nil`. +- Replace Sass and Autoprefixer `npm` build scripts with [Jekyll's built-in asset support](https://jekyllrb.com/docs/assets/). [#333](https://github.com/mmistakes/minimal-mistakes/issues/333) + +### Maintenance + +- Document `site.repository` and its role with [`github-metadata`](https://github.com/jekyll/github-metadata) gem. +- Add sample [archive page with content](https://mmistakes.github.io/minimal-mistakes/archive-layout-with-content/) for testing styles on demo site. + +## [3.3.6](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.3.6) + +### Bug Fixes + +- Fix blank `site.teaser` bug [#412](https://github.com/mmistakes/minimal-mistakes/issues/412) + +## [3.3.5](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.3.5) + +### Enhancements + +- Add English default text `site.locale` strings [#407](https://github.com/mmistakes/minimal-mistakes/issues/407) +- Add Portuguese localized UI text. [#411](https://github.com/mmistakes/minimal-mistakes/pull/411) +- Add Italian localized UI text. [#409](https://github.com/mmistakes/minimal-mistakes/pull/409) + +### Maintenance + +- Remove unused Google AdSense variables in `_config.yml` [#404](https://github.com/mmistakes/minimal-mistakes/issues/404) +- Update `Gemfile` instructions for using `github-pages` vs. native `jekyll` gems. +- Disable `gems:` in `_config.yml` and enable plugins with Bundler instead. +- Add `repository` to `_config.yml` to suppress GitHub Pages error `Liquid Exception: No repo name found.` + +## [3.3.4](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.3.4) + +### Enhancements + +- Add support for configurable feed URL to use a service like FeedBurner instead of linking directly to `feed.xml` in `<head>` and the site footer. [#378](https://github.com/mmistakes/minimal-mistakes/issues/378), [#379](https://github.com/mmistakes/minimal-mistakes/pull/379), [#406](https://github.com/mmistakes/minimal-mistakes/pull/406) +- Add Turkish localized UI text. [#403](https://github.com/mmistakes/minimal-mistakes/pull/403) + +### Maintenance + +- Update gems: `activesupport` (4.2.7), `ffi` (1.9.14), `github-pages` (88), `jekyll-redirect-from` (0.11.0), `jekyll-watch` (1.5.0). + +## [3.3.3](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.3.3) + +### Enhancements + +- Make footer stick to the bottom of the page. + +### Bug Fixes + +- Fix `gallery` size bug [#402](https://github.com/mmistakes/minimal-mistakes/issues/402) + +### Maintenance + +- Set default `lang` to `en`. + +### Enhancements + +- Make footer stick to the bottom of the page. + +### Bug Fixes + +- Fix `gallery` size bug [#402](https://github.com/mmistakes/minimal-mistakes/issues/402) + +### Maintenance + +- Set default `lang` to `en`. + +## [3.3.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.3.2) + +### Bug Fixes + +- Fix JavaScript that triggers "sticky" sidebar to avoid layout issues on screen sizes < `1024px`. [#396](https://github.com/mmistakes/minimal-mistakes/issues/396) + +## [3.3.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.3.1) + +### Enhancements + +- Enable image popup on < 500px wide screens. [#385](https://github.com/mmistakes/minimal-mistakes/issues/385) +- Indicate the relationship between component URLs in a paginated series by applying `rel="prev"` and `rel="next"` to pages that use `site.paginator`. [#253](https://github.com/mmistakes/minimal-mistakes/issues/253) +- Improve link posts in archive listings. [#276](https://github.com/mmistakes/minimal-mistakes/issues/276) + +### Maintenance + +- Update gems: `github-pages` (86), `ffi` 1.9.13, `jekyll-mentions` 1.1.3, and `rouge` 1.11.1 +- Fix note about custom sidebar content appearing below author profile. [#388](https://github.com/mmistakes/minimal-mistakes/issues/388) + +## [3.2.13](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.13) + +### Enhancement + +- Add English default UI text for Canada, Great Britain, and Australia. [#377](https://github.com/mmistakes/minimal-mistakes/issues/377) +- Switch default locale from `en-US` to `en`. + +## [3.2.12](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.12) + +### Enhancements + +- Remove window width "magic number" from sticky sidebar check in `main.js` for improved flexibility. [#375](https://github.com/mmistakes/minimal-mistakes/pull/375) + +### Bug Fixes + +- Fix author override conditional where a missing `authors.yml` would show broken sidebar content. Defaults to `site.author`. [#376](https://github.com/mmistakes/minimal-mistakes/pull/376) + +## [3.2.11](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.11) + +### Bug Fixes + +- Fix disappearing author sidebar links [#372](https://github.com/mmistakes/minimal-mistakes/issues/372) + +### Maintenance + +- Update gems: `github-pages` (84), `jekyll-github-metadata` 2.0.2, and `kramdown` 1.11.1 +- Update vendor JavaScript: jQuery 1.12.4, Stickyfill.js 1.1.4 +- Update Font Awesome 4.6.3 + +## [3.2.10](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.10) + +### Maintenance + +- Add `CONTRIBUTING.md` + +## [3.2.9](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.9) + +### Enhancements + +- Add support for [header overlay images](https://mmistakes.github.io/minimal-mistakes/docs/layouts/#header-overlay) for Open Graph images. [#358](https://github.com/mmistakes/minimal-mistakes/pull/358) + +### Bug Fixes + +- Fix `Person` typo Schema.org type [#358](https://github.com/mmistakes/minimal-mistakes/pull/358) + +### Maintenance + +- Update `github-pages` gem and dependencies. +- Remove `minutes_read` to avoid awkward reading time wording [#356](https://github.com/mmistakes/minimal-mistakes/issues/356) + +## [3.2.8](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.8) + +### Bug Fixes + +- Remove `cursor: pointer` that appears on white-space surrounding author side list items and links. [#354](https://github.com/mmistakes/minimal-mistakes/pull/354) + +### Maintenance + +- Add contributing information to `README.md`. [#357](https://github.com/mmistakes/minimal-mistakes/issues/357) + +## [3.2.7](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.7) + +### Enhancements + +- Add French localized UI text. [#346](https://github.com/mmistakes/minimal-mistakes/pull/346) + +### Bug Fixes + +- Fix branch logic for Yandex and Alexa in `seo.html`. [#348](https://github.com/mmistakes/minimal-mistakes/pull/348) + +## [3.2.6](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.6) + +### Bug Fixes + +- Fix error `Liquid Exception: divided by 0 in _includes/archive-single.html, included in _layouts/single.html` caused by null `words_per_minute` in `_config.yml`. [#345](https://github.com/mmistakes/minimal-mistakes/pull/345) + +## [3.2.5](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.5) + +### Bug Fixes + +- Fix link color in hero overlay to be white. +- Remove underlines from archive item titles. + +## [3.2.4](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.4) + +### Enhancements + +- Improve text alignment of masthead, hero overlay, page footer to be flush left and remove awkward white-space gaps. [#342](https://github.com/mmistakes/minimal-mistakes/issues/342) +- Add Spanish localized UI text. [#338](https://github.com/mmistakes/minimal-mistakes/pull/338) + +### Bug Fixes + +- Fix alignment of icons in author sidebar [#341](https://github.com/mmistakes/minimal-mistakes/issues/341) + +### Maintenance + +- Add background color to page footer to set it apart from main content. [#342](https://github.com/mmistakes/minimal-mistakes/issues/342) +- Add terms and privacy policy to theme's demo site. [#343](https://github.com/mmistakes/minimal-mistakes/issues/343) +- Update screenshots found in theme documentation. + +## [3.2.3](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.3) + +### Enhancement + +- Add [Discourse](https://www.discourse.org/) as a commenting provider [#335](https://github.com/mmistakes/minimal-mistakes/pull/335) + +## [3.2.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.2) + +### Enhancement + +- Add support for image captions in Magnific Popup overlays via the [`gallery`](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#gallery) helper [#334](https://github.com/mmistakes/minimal-mistakes/issues/334) + +## [3.2.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.1) + +### Bug Fixes + +- Remove need for "double tapping" masthead menu links on iOS devices. [#315](https://github.com/mmistakes/minimal-mistakes/issues/315) + +### Maintenance + +- Add `ISSUE_TEMPLATE.md` for improve issue submission process. + +## [3.2.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.2.0) + +### Bug Fixes + +- Fix missing category/tag links in post footer due to possible conflict with `site.tags` and `site.categories`. [#329](https://github.com/mmistakes/minimal-mistakes/issues/329#issuecomment-222375568) + +## [3.1.8](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.1.8) + +### Bug Fixes + +- Fix `Liquid Exception: undefined method 'gsub' for nil:NilClass in _layouts/single.html` error when `page.title` is null. `<h1>` element is now conditional if `title:` is not set for a `page` or collection item. [#312](https://github.com/mmistakes/minimal-mistakes/issues/312) + +### Maintenance + +- Remove duplicate `fa-twitter` and `fa-twitter-square` classes from `_utilities.scss`. [#302](https://github.com/mmistakes/minimal-mistakes/issues/302) + +- Document installing additional Jekyll gem dependencies when using `gem "jekyll"` instead of `gem "github-pages"` to avoid any errors on run. [#305](https://github.com/mmistakes/minimal-mistakes/issues/305) + +## [3.1.7](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.1.7) + +### Enhancement + +- Add translation key for "Recent Posts" used in home page `index.html`. [#316](https://github.com/mmistakes/minimal-mistakes/pull/316) + +### Maintenance + +- Small fix to avoid underlying the whitespace between icons and related text when hovering. [#303](https://github.com/mmistakes/minimal-mistakes/pull/303) + +## [3.1.6](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.1.6) + +### Maintenance + +- Update gem dependencies. Run `bundle` to update `Gemfile.lock`. + +## [3.1.5](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.1.5) + +### Maintenance + +- Fix `www` and `https` links in author profile include [#293](https://github.com/mmistakes/minimal-mistakes/pull/293) + +## [3.1.4](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.1.4) + +### Enhancements + +- Add `overlay_filter` param to hero headers [#298](https://github.com/mmistakes/minimal-mistakes/pull/298) + +## [3.1.3](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.1.3) + +### Enhancements + +- Improve `site.locale` documentation [#284](https://github.com/mmistakes/minimal-mistakes/issues/284) +- Remove ProTip note about protocol-less `site.url` as it is an anti-pattern [#288](https://github.com/mmistakes/minimal-mistakes/issues/288) + +### Bug Fixes + +- Fix `og_image` URL in seo.html [#277](https://github.com/mmistakes/minimal-mistakes/issues/277) +- Fix `author_profile` toggle when assigned in a `_layout` [#285](https://github.com/mmistakes/minimal-mistakes/issues/285) +- Fix typo in `build:all` npm script [#283](https://github.com/mmistakes/minimal-mistakes/pull/283) +- Fix URL typo documentation [#287](https://github.com/mmistakes/minimal-mistakes/issues/287) +- SEO author bug. If `twitter.username` is set and `author.twitter` is `nil` bad things happen. [#289](https://github.com/mmistakes/minimal-mistakes/issues/289) + +## [3.1.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.1.2) + +### Enhancement + +- Explain how to use `nav_list` helper in [documentation](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#navigation-list). +- Reduce left/right padding on smaller screens to increase width of main content column. + +## [3.1.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.1.1) + +### Bug Fix + +- Fixed reading time bug when `words_per_minute` wasn't set in `_config.yml` [#271](https://github.com/mmistakes/minimal-mistakes/issues/271) + +## [3.1.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.1.0) + +### Enhancements + +- Updated [Font Awesome](https://fortawesome.github.io/Font-Awesome/whats-new/) to version 4.6.1 +- Added optional GitHub and Bitbucket links to footer if set on `site.author` in `_config.yml`. + +### Bug Fixes + +- Fixed Bitbucket URL typo in author sidebar. + +## [3.0.3](https://github.com/mmistakes/minimal-mistakes/releases/tag/3.0.3) + +### Enhancements + +- Rebuilt the entire theme: layouts, includes, stylesheets, scripts, you name it. +- Refreshed the look and feel while staying true to the original design of the theme (author sidebar/main content). +- Replaced grid system with [Susy](http://susy.oddbird.net/). +- Replaced Grunt tasks with `npm` scripts. +- Removed Google Fonts and replaced with system fonts to improve performance (they can be [added back](https://mmistakes.github.io/minimal-mistakes/docs/stylesheets/) if desired) +- Greatly improved [theme documentation](https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/). +- Increased the amount of sample posts, sample pages, and sample collections to throughly test the theme and edge-cases. +- Moved all sample content and assets out of `master` to keep it as clean as possible for forking. +- Added new layouts for `splash` pages, archives for [`jekyll-archives`](https://github.com/jekyll/jekyll-archives) if enabled, and [`compress.html`](https://github.com/penibelst/jekyll-compress-html) to improve performance. +- Added taxonomy links to posts (tags and categories). +- Added optional "reading time" meta data. +- Improved Liquid used for Twitter Cards and Open Graph data in `<head>`. +- Improved `gallery` include helper and added `feature_row` for use with splash page layout. +- Added Keybase.io, author web URI, and Bitbucket optional links to sidebar. +- Add `feed.xml` link to footer. +- Added a [UI text data file](https://mmistakes.github.io/minimal-mistakes/docs/ui-text/) to easily change all text found in the theme. +- Added LinkedIn to optional social share buttons. +- Added Facebook, Google+, and custom commenting options in addition to Disqus. +- Added optional breadcrumb links. + +## [2.2.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/2.2.1) + +## [2.2.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/2.2.0) + +### Enhancements + +- Add support for Jekyll 3.0 +- Minor updates to syntax highlighting CSS and theme documentation + +## [2.1.3](https://github.com/mmistakes/minimal-mistakes/releases/tag/2.1.3) + +### Enhancements + +- Cleaner print styles that remove the top navigation, social sharing buttons, and other elements not needed when printed. + +## [2.1.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/2.1.2) + +### Enhancements + +- Add optional CodePen icon/url to author side bar [#156](https://github.com/mmistakes/minimal-mistakes/pull/156) +- Documented Stackoverflow username explanation in `_config.yml` [#157](https://github.com/mmistakes/minimal-mistakes/pull/157) +- Simplified Liquid in `post-index.html` to better handle year listings [#166](https://github.com/mmistakes/minimal-mistakes/pull/166) + +### Bug Fixes + +- Cleanup Facebook related Open Graph meta tags [#149](https://github.com/mmistakes/minimal-mistakes/issues/149) +- Corrected minor typos [#158](https://github.com/mmistakes/minimal-mistakes/pull/158) [#175](https://github.com/mmistakes/minimal-mistakes/issues/175) + +## [2.1.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/2.1.1) + +### Enhancements + +- Add optional XING profile link to author sidebar +- Include open graph meta tags for feature image (if assigned) [#149](https://github.com/mmistakes/minimal-mistakes/issues/149) +- Create an include for feed footer + +### Bug Fixes + +- Remove http protocol from Google search form on sample 404 page +- Only show related posts if there are one or more available +- Fix alignment of email address link in author sidebar + +## [2.1.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/2.1.0) + +### Enhancements + +- Add optional social sharing buttons ([#42](https://github.com/mmistakes/minimal-mistakes/issues/42)) + +![social sharing buttons](https://cloud.githubusercontent.com/assets/1376749/5860522/d9f28a96-a22f-11e4-9b83-940a3a9a766a.png) + +- Add Soundcloud, YouTube ([#95](https://github.com/mmistakes/minimal-mistakes/pull/95)), Flickr ([#119](https://github.com/mmistakes/minimal-mistakes/pull/119)), and Weibo ([#116](https://github.com/mmistakes/minimal-mistakes/pull/116)) icons for use in author sidebar. +- Fix typos in posts and documentation and remove references to Less +- Include note about Octopress gem being optional +- Post author override support extended to the Atom feed ([#71](https://github.com/mmistakes/minimal-mistakes/pull/71)) +- Only include email address in feed if specified in `_config.yml` or author `_data` +- Wrap all page content in `#main` to harmonize article and post index styles ([#86](https://github.com/mmistakes/minimal-mistakes/issues/86)) +- Include new sample feature images for posts and pages +- Table of contents improvements: fix collapse toggle, indent nested elements, show on small screens, and create an `_include` for reusing in posts and pages. +- Include note about running Jekyll with `bundle exec` when using Bundler +- Fix home page path in top navigation +- Remove Google Authorship ([#120](https://github.com/mmistakes/minimal-mistakes/issues/120)) +- Remove duplicate author content that displayed in `div.article-author-bottom` +- Removed unused `_sass/print.scss` styles +- Improve comments in `.scss` files + +## [2.0.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/v2.0) + +## [1.3.3](https://github.com/mmistakes/minimal-mistakes/releases/tag/1.3.3) + +### Enhancements + +- Added new icons and profile links for Stackoverflow, Dribbble, Pinterest, Foursquare, and Steam to the author bio sidebar. +- Cleaned up the Kramdown auto table of contents styling to be more readable +- Removed page width specific .less stylesheets and created mixins for easier updating +- Removed Modernizr since it wasn't being used +- Added pages to sitemap.xml +- Added category: to rake new_post task +- Minor typographic changes + +### Bug Fixes + +- Corrected various broken links in README and Theme Setup. + +## [1.3.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/1.3.1) + +### Enhancements + +- Cleaned up table of contents styling +- Reworked top navigation to be a better experience on small screens. Nav items now display vertically when the menu button is tapped, revealing links with larger touch targets. + +![menu animation](https://camo.githubusercontent.com/3fbd8c1326485f4b1ab32c0005c0fca7660b5d31/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f313337363734392f323136343037352f31653366303663322d393465372d313165332d383961612d6436623636376562306564662e676966) + +## [1.2.0](https://github.com/mmistakes/minimal-mistakes/releases/tag/1.2.0) + +### Bug Fixes + +- Table weren't filling the entire width of the content container. They now scale at 100%. Thanks [@dhruvbhatia](https://github.com/dhruvbhatia) + +### Enhancements + +- Decreased spacing between Markdown footnotes +- Removed dark background on footer +- Removed UPPERCASE styling on post titles in the index listing + +## [1.1.4](https://github.com/mmistakes/minimal-mistakes/releases/tag/1.1.4) + +### Bug Fixes + +- Fix top navigation bug issue ([#10](https://github.com/mmistakes/minimal-mistakes/issues/10)) for real this time. Remember to clear your floats kids. + +## [1.1.3](https://github.com/mmistakes/minimal-mistakes/releases/tag/1.1.3) + +### Bug Fixes + +- Fix top navigation links that weren't click able on small viewports (Issue [#10](https://github.com/mmistakes/minimal-mistakes/issues/10)). +- Remove line wrap from top navigation links that may span multiple lines. + +## [1.1.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/1.1.2) + +### Enhancements + +- Added Grunt build script for compiling Less/JavaScript and optimizing image assets. +- Added support for large image summary Twitter card. +- Stylesheet adjustments + +## [1.1.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/1.1.1) + +### Bug Fixes + +- Removed [Typeplate](http://typeplate.com/) styles. Was [causing issues with newer versions of Less](https://github.com/typeplate/typeplate.github.io/issues/108) and is no longer maintained. + +### Enhancements + +- Added [image attribution](http://mmistakes.github.io/minimal-mistakes/theme-setup/#feature-images) for post and page feature images. +- Added [404 page](http://mmistakes.github.io/minimal-mistakes/404.html). +- Cleaned up various Less variables to better align with naming conventions used in other MM Jekyll themes. +- Removed Chrome Frame references. +- Added global CSS3 transitions to text and block elements. +- Improved typography in a few places. + +## [1.0.2](https://github.com/mmistakes/minimal-mistakes/releases/tag/v1.0.2) + +### Enhancements + +- Google Analytics, Google Authorship, webmaster verifies, and Twitter card meta are now optional. + +## [1.0.1](https://github.com/mmistakes/minimal-mistakes/releases/tag/v1.0.1) diff --git a/docs/19-contributing.md b/docs/19-contributing.md new file mode 100644 index 00000000..1d12ed79 --- /dev/null +++ b/docs/19-contributing.md @@ -0,0 +1,15 @@ +Having trouble working with the theme? Found a typo in the documentation? Interested in adding a feature or [fixing a bug](https://github.com/mmistakes/minimal-mistakes/issues)? Then by all means [submit an issue](https://github.com/mmistakes/minimal-mistakes/issues/new) or [pull request](https://help.github.com/articles/using-pull-requests/). If this is your first pull request, it may be helpful to read up on the [GitHub Flow](https://guides.github.com/introduction/flow/) first. + +Minimal Mistakes has been designed as a base for you to customize and fit your site's unique needs. Please keep this in mind when requesting features and/or submitting pull requests. If it's not something that most people will use, I probably won't consider it. When in doubt ask. + +This goes for author sidebar links and "share button" additions -- I have no intention of merging in every possibly option, the essentials are there to get you started :smile:. + +## Pull requests + +When submitting a pull request: + +1. Clone the repo. +2. Create a branch off of `master` and give it a meaningful name (e.g. `my-awesome-new-feature`) and describe the feature or fix. +3. Open a pull request on GitHub. + +Theme documentation and demo pages can be found in the [`/docs`](https://github.com/{{ site.repository }}/blob/master/docs) folder if you'd like to tackle any "low-hanging fruit" like fixing typos, bad grammar, etc. \ No newline at end of file diff --git a/docs/20-docs-2-2.md b/docs/20-docs-2-2.md new file mode 100644 index 00000000..821fe9fe --- /dev/null +++ b/docs/20-docs-2-2.md @@ -0,0 +1,292 @@ +## Installation + +Minimal Mistakes now requires [Jekyll](http://jekyllrb.com/) 3.0. Make sure to run `bundle update` if you aren't on the latest version to update all gem dependencies. + +If you are creating a new Jekyll site using Minimal Mistakes follow these steps: + +1. Fork the [Minimal Mistakes repo](http://github.com/mmistakes/minimal-mistakes/fork). +2. Clone the repo you just forked and rename it. +3. [Install Bundler](http://bundler.io) `gem install bundler` and Run `bundle install` to install all dependencies (Jekyll, [Jekyll-Sitemap](https://github.com/jekyll/jekyll-sitemap), [Octopress](https://github.com/octopress/octopress), etc) +4. Update `config.yml`, add navigation, and replace demo posts and pages with your own. Full details below. + +If you want to use Minimal Mistakes with an existing Jekyll site follow these steps: + +1. [Download Minimal Mistakes](https://github.com/mmistakes/minimal-mistakes/releases/tag/2.2.1) and unzip. +2. Rename `minimal-mistakes-master` to something meaningful ie: `new-site` +3. Run `bundle install` to install all dependencies (Jekyll, [Jekyll-Sitemap](https://github.com/jekyll/jekyll-sitemap), [Octopress](https://github.com/octopress/octopress), etc) +4. Remove demo posts/pages and replace with your own posts, pages, and any other content you want to move over. +5. Update posts' and pages' YAML to match variables used by Minimal Mistakes. Full details below. +6. Update `_config.yml` and add navigation links. Full details below. + +**Pro-tip:** Delete the `gh-pages` branch after cloning and start fresh by branching off `master`. There is a bunch of garbage in `gh-pages` used for the theme's demo site that I'm guessing you won't want. +{: .notice} + +## Running Jekyll + +The preferred method for running Jekyll is with `bundle exec`, but if you're willing to deal gem conflicts feel free to go cowboy with a `jekyll serve` or `jekyll build`. + +> In some cases, running executables without bundle exec may work, if the executable happens to be installed in your system and does not pull in any gems that conflict with your bundle. +> +>However, this is unreliable and is the source of considerable pain. Even if it looks like it works, it may not work in the future or on another machine. + +```bash +bundle exec jekyll serve +``` + +## Scaffolding + +How Minimal Mistakes is organized and what the various files are. All posts, layouts, includes, stylesheets, assets, and whatever else is grouped nicely under the root folder. The compiled Jekyll site outputs to `_site/`. + +```bash +minimal-mistakes/ +├── _includes/ +| ├── author-bio.html # bio stuff layout. pulls optional owner data from _config.yml +| ├── browser-upgrade # prompt to install a modern browser for < IE9 +| ├── disqus-comments # Disqus comments script +| ├── footer # site footer +| ├── head # site head +| ├── navigation # site top navigation +| ├── open-graph.html # Twitter Cards and Open Graph meta data +| └── scripts # site scripts +├── _layouts/ +| ├── home.html # homepage layout +| ├── page.html # page layout +| ├── post-index.html # post index layout +| └── post.html # single post layout +├── _posts/ # MarkDown formatted posts +├── _sass/ # Sass stylesheets +├── _templates/ # used by Octopress to define YAML variables for new posts/pages +├── about/ # sample about page +├── assets/ +| ├── css/ # compiled stylesheets +| ├── fonts/ # webfonts +| ├── js/ +| | ├── _main.js # main JavaScript file, plugin settings, etc +| | ├── plugins/ # scripts and jQuery plugins to combine with _main.js +| | ├── scripts.min.js # concatenated and minified _main.js + plugin scripts +| | └── vendor/ # vendor scripts to leave alone and load as is +| └── less/ +├── images/ # images for posts and pages +├── 404.md # 404 page +├── feed.xml # Atom feed template +├── index.md # sample homepage. lists 5 latest posts +├── posts/ # sample post index page. lists all posts in reverse chronology +└── theme-setup/ # theme setup page. safe to remove +``` + +## Site Setup + +A quick checklist of the files you'll want to edit to get up and running. + +### Site Wide Configuration + +`_config.yml` is your friend. Open it up and personalize it. Most variables are self explanatory but here's an explanation of each if needed: + +#### title + +The title of your site... shocker! + +Example `title: My Awesome Site` + +#### url + +Used to generate absolute urls in `sitemap.xml`, `feed.xml`, and for generating canonical URLs in `<head>`. When developing locally either comment this out or use something like `http://localhost:4000` so all assets load properly. *Don't include a trailing `/`*. + +Examples: + +```yaml +url: http://mmistakes.github.io/minimal-mistakes +url: http://localhost:4000 +url: //cooldude.github.io +url: +``` + +#### Google Analytics and Webmaster Tools + +Google Analytics UA and Webmaster Tool verification tags can be entered under `owner` in `_config.yml`. For more information on obtaining these meta tags check [Google Webmaster Tools](http://support.google.com/webmasters/bin/answer.py?hl=en&answer=35179) and [Bing Webmaster Tools](https://ssl.bing.com/webmaster/configure/verify/ownership) support. + +### Navigation Links + +To set what links appear in the top navigation edit `_data/navigation.yml`. Use the following format to set the URL and title for as many links as you'd like. *External links will open in a new window.* + +```yaml +- title: Portfolio + url: /portfolio/ + +- title: Made Mistakes + url: http://mademistakes.com +``` + +## Adding New Content with Octopress + +While completely optional, I've included Octopress and some starter templates to automate the creation of new posts and pages. To take advantage of it start by installing the [Octopress](https://github.com/octopress/octopress) gem if it isn't already. + +```bash +$ gem install octopress +``` + +### New Post + +Default command + +```bash +$ octopress new post "Post Title" +``` + +Default works great if you want all your posts in one directory, but if you're like me and want to group them into subfolders like `/posts`, `/portfolio`, etc. Then this is the command for you. By specifying the DIR it will create a new post in that folder and populate the `categories:` YAML with the same value. + +```bash +$ octopress new post "New Portfolio Post Title" --dir portfolio +``` + +### New Page + +To create a new page use the following command. + +```bash +$ octopress new page new-page/ +``` + +This will create a page at `/new-page/index.md` + +## Layouts and Content + +Explanations of the various `_layouts` included with the theme and when to use them. + +### Post and Page + +These two layouts are very similar. Both have an author sidebar, allow for large feature images at the top, and optional Disqus comments. The only real difference is the post layout includes related posts at the end of the page. + +### Post Index Page + +A [sample index page]({{ site.url }}/posts/) listing all posts grouped by the year they were published has been provided. The name can be customized to your liking by editing a few references. For example, to change **Posts** to **Writing** update the following: + +In `_config.yml` under `links:` rename the title and URL to the following: + +```yaml + links: + - title: Writing + url: /writing/ +``` + +* Rename `posts/index.md` to `writing/index.md` and update the YAML front matter accordingly. +* Update the **View all posts** link in the `post.html` layout found in `_layouts` to match title and URL set previously. + +### Feature Images + +A good rule of thumb is to keep feature images nice and wide so you don't push the body text too far down. An image cropped around around 1024 x 256 pixels will keep file size down with an acceptable resolution for most devices. If you want to serve these images responsively I'd suggest looking at the [Jekyll Picture Tag](https://github.com/robwierzbowski/jekyll-picture-tag) plugin[^plugins]. + +[^plugins]: If you're using GitHub Pages to host your site be aware that plugins are disabled. You'll need to build your site locally and then manually deploy if you want to use this sweet plugin. + +The post and page layouts make the assumption that the feature images live in the `images/` folder. To add a feature image to a post or page just include the filename in the front matter like so. It's probably best to host all your images from this folder, but you can hotlink from external sources if you desire. + +```yaml +image: + feature: feature-image-filename.jpg + thumb: thumbnail-image.jpg #keep it square 200x200 px is good +``` + +To add attribution to a feature image use the following YAML front matter on posts or pages. Image credits appear directly below the feature image with a link back to the original source if supplied. + +```yaml +image: + feature: feature-image-filename.jpg + credit: Michael Rose #name of the person or site you want to credit + creditlink: http://mademistakes.com #url to their site or licensing +``` + +### Thumbnails for OG and Twitter Cards + +Feature and thumbnail images are used by [Open Graph](https://developers.facebook.com/docs/opengraph/) and [Twitter Cards](https://dev.twitter.com/docs/cards) as well. If you don't assign a thumbnail the default graphic *(default-thumb.png)* is used. I'd suggest changing this to something more meaningful --- your logo or avatar are good options. + +**Pro-Tip**: You need to [apply for Twitter Cards](https://dev.twitter.com/docs/cards) before they will begin showing up when links to your site are shared. +{:.notice} + +### Author Override + +By making use of data files you can assign different authors for each post. + +Start by modifying `authors.yml` file in the `_data` folder and add your authors using the following format. + +```yaml +# Authors + +billy_rick: + name : "Billy Rick" + web : "http://thewhip.com" + email : "billy@rick.com" + bio : "What do you want, jewels? I am a very extravagant man." + avatar : "bio-photo-2.jpg" + twitter : "extravagantman" + google_plus : "BillyRick" + +cornelius_fiddlebone: + name : "Cornelius Fiddlebone" + email : "cornelius@thewhip.com" + bio : "I ordered what?" + avatar : "bio-photo.jpg" + twitter : "rhymeswithsackit" + google_plus : "CorneliusFiddlebone" +``` + +To assign Billy Rick as an author for our post. We'd add the following YAML front matter to a post: + +```yaml +author: billy_rick +``` + +### Kramdown Table of Contents + +To include an auto-generated **table of contents** for posts and pages, add the following `_include` before the actual content. [Kramdown will take care of the rest](http://kramdown.rubyforge.org/converter/html.html#toc) and convert all headlines into list of links. + +```html +{% raw %}{% include toc.html %}{% endraw %} +``` + +### Paragraph Indentation + +By default the margin below paragraphs has been removed and indent added to each. This is an intentional design decision to mimic the look of type set in a printed book or manuscript. + +<figure> + <img src="{{ '/assets/images/paragraph-indent.png' | relative_url }}" alt="screen shot of paragraphs with default indent style set"> + <figcaption>Example of the default paragraph style (indented first line and bottom margin removed).</figcaption> +</figure> + +To disable the indents and add spacing between paragraphs change the following line in `_sass/variables.scss` from `true !default` to `false` like so. + +```scss +$paragraph-indent: false; +``` + +<figure> + <img src="{{ '/assets/images/paragraph-no-indent.png' | relative_url }}" alt="screen shot of paragraphs with indent style disabled"> + <figcaption>Example of paragraphs with $paragraph-indent disabled.</figcaption> +</figure> + +### Videos + +Video embeds are responsive and scale with the width of the main content block with the help of [FitVids](http://fitvidsjs.com/). + +Not sure if this only effects Kramdown or if it's an issue with Markdown in general. But adding YouTube video embeds causes errors when building your Jekyll site. To fix add a space between the `<iframe>` tags and remove `allowfullscreen`. Example below: + +```html +<iframe width="560" height="315" src="http://www.youtube.com/embed/PWf4WUoMXwg" frameborder="0"> </iframe> +``` + +### Social Sharing Links + +Social sharing links for Twitter, Facebook, and Google+ are included on posts/pages by default. To hide them on specific posts or pages add `share: false` to the YAML Front Matter. If you'd like to use different social networks modify `_includes/social-share` to your liking. Icons are set using [Font Awesome](http://fontawesome.io). + +## Further Customization + +Jekyll 2.x added support for Sass files making it much easier to modify a theme's fonts and colors. By editing values found in `_sass/variables.scss` you can fine tune the site's colors and typography. + +For example if you wanted a red background instead of white you'd change `$bodycolor: #fff;` to `$bodycolor: $cc0033;`. + +To modify the site's JavaScript files I setup a Grunt build script to lint/concatenate/minify all scripts into `scripts.min.js`. [Install Node.js](http://nodejs.org/), then [install Grunt](http://gruntjs.com/getting-started), and then finally install the dependencies for the theme contained in `package.json`: + +```bash +npm install +``` + +From the theme's root, use `grunt` concatenate JavaScript files, and optimize .jpg, .png, and .svg files in the `images/` folder. You can also use `grunt dev` in combination with `jekyll build --watch` to watch for updates JS files that Grunt will then automatically re-build as you write your code which will in turn auto-generate your Jekyll site when developing locally. \ No newline at end of file diff --git a/docs/21-license.md b/docs/21-license.md new file mode 100644 index 00000000..2f9d224a --- /dev/null +++ b/docs/21-license.md @@ -0,0 +1,83 @@ + +The MIT License (MIT) + +Hasp-lvgl is Copyright (c) 2019-{{ site.time | date: '%Y' }} fvanroie, netwize.be and contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +------------------------------------------- +Hasp-lvgl is based on the previous work of the following open source developers: + +- [HASwitchPlate](https://github.com/aderusha/HASwitchPlate), the original Arduino project, + Copyright© 2019 Allen Derusha. + HASwitchPlate is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT). + +- [LVGL](https://lvgl.io/) graphics library, + Copyright© 2016 Gábor Kiss-Vámosi and + Copyright (c) 2020 LVGL LLC. + LVGL is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT). + +- [TFT_eSPI](https://github.com/Bodmer/TFT_eSPI) display library, + Copyright© 2020 Bodmer (https://github.com/Bodmer) All rights reserved. + TFT_eSPI is distributed under the terms of the [FreeBSD License](https://opensource.org/licenses/BSD-2-Clause) + and includes parts from the [Adafruit_GFX library](https://github.com/adafruit/Adafruit-GFX-Library), + Copyright© 2012 Adafruit Industries. All rights reserved. + Adafruit_GFX is distributed under the terms of the [BSD License](https://opensource.org/licenses/BSD-2-Clause) + +- zi Font Engine + Copyright© 2020 fvanroie, netwize.be + [MIT License](http://opensource.org/licenses/MIT). + +- [ArduinoJson](https://arduinojson.org/) + Copyright© 2014-2020 Benoit BLANCHON + [MIT License](http://opensource.org/licenses/MIT). + +- [PubSubClient](https://github.com/knolleary/pubsubclient) + Copyright© 2008-2015 Nicholas O'Leary + [MIT License](http://opensource.org/licenses/MIT). + +- Logging engine is based on [ArduinoLog](https://github.com/thijse/Arduino-Log), + Copyright© 2017,2018 Thijs Elenbaas, MrRobot62, rahuldeo2047, NOX73, dhylands, Josha blemasle, mfalkvidd + with modifications by fvanroie, netwize.be. + ArduinoLog is distributed under the terms of the [MIT License](http://opensource.org/licenses/MIT). + +- [Syslog library](https://github.com/arcao/Syslog), + Copyright© 2016 Martin Sloup + [MIT License](http://opensource.org/licenses/MIT). + +- [QR Code generator](https://github.com/nayuki/QR-Code-generator) + Copyright© Project Nayuki + [MIT License](http://opensource.org/licenses/MIT). + +- [AceButton](https://github.com/bxparks/AceButton) + Copyright© 2018 Brian T. Park + [MIT License](http://opensource.org/licenses/MIT). + +- Custom zi Fonts incorporate [Font Awesome](http://fontawesome.io/), + Copyright© 2017 Dave Gandy. + Font Awesome is distributed under the terms of the [SIL OFL 1.1](http://scripts.sil.org/OFL) + and [MIT License](http://opensource.org/licenses/MIT). + +- The bootscreen uses the [MaterialDesign Icons](https://materialdesignicons.com/) font, + Copyright© 2014, Austin Andrews (http://materialdesignicons.com/), + MaterialDesign Icons font is licensed under the SIL Open Font License, Version 1.1. + +- This website theme is based on [Minimal Mistakes](https://mmistakes.github.io/minimal-mistakes/), + Copyright© 2013-2020 Michael Rose and contributors + [MIT License](http://opensource.org/licenses/MIT). diff --git a/docs/38-firmware-esp.md b/docs/38-firmware-esp.md new file mode 100644 index 00000000..dfb3f1e9 --- /dev/null +++ b/docs/38-firmware-esp.md @@ -0,0 +1,18 @@ + +## ESP Firmware Update + +### Serial Upload + +Either use Tasmotizer or esptool.py to upload a new firmware file to the ESP. This procedure is the same as the initial installation. + +### HTTP Upload + +When the ESP has previously been flashed via serial, you can upload a new firmware file using the internal webserver. + +### HTTP Update + +When the ESP has previously been flashed via serial you can download and install new firmware directly from an external webserver. + +### OTA Upload + +When the ESP has previously been flashed via serial, subsequent updates can be performed Over-the-Air from within PlatformIO. diff --git a/docs/39-firmware-stm32.md b/docs/39-firmware-stm32.md new file mode 100644 index 00000000..2b62e224 --- /dev/null +++ b/docs/39-firmware-stm32.md @@ -0,0 +1 @@ +## STM32F4xx Firmware Update diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 00000000..8f32f743 --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,18 @@ +# Changelog + +All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. + +## [0.3.0](https://github.com/anikethsaha/docsify-changelog-plugin/compare/v0.2.0...v0.3.0) (2020-02-11) + + + +## [0.2.0](https://github.com/anikethsaha/docsify-changelog-plugin/compare/v0.1.0...v0.2.0) (2020-02-11) + + +### Bug Fixes + +* major fix and added docs ([af58522](https://github.com/anikethsaha/docsify-changelog-plugin/commit/af58522)) + + + +## 0.1.0 (2020-02-11) \ No newline at end of file diff --git a/docs/Configuration/30-http.md b/docs/Configuration/30-http.md new file mode 100644 index 00000000..f790b546 --- /dev/null +++ b/docs/Configuration/30-http.md @@ -0,0 +1,9 @@ +### Setup HTTP User Athentication + +To restrict access to the web user interface you can set a Username and Password. + +![HTTP configuration](assets/images/settings/configuration.png "HTTP configuration") + +Click 'Save Settings' to activate. + +* Please note that all http communication is unencrypted and that this is only a simple security measure \ No newline at end of file diff --git a/docs/Configuration/32-mqtt.md b/docs/Configuration/32-mqtt.md new file mode 100644 index 00000000..ba3be6cd --- /dev/null +++ b/docs/Configuration/32-mqtt.md @@ -0,0 +1,49 @@ + +## MQTT + +All communication between **HASP Open Display** and your Home Automation service is done over MQTT. You will need an already working MQTT Broker. + +:question: If you do not know what MQTT is you can find more about the protocol on [MQTT Essentials](http://www.hivemq.com/mqtt-essentials/) + +![MQTT Settings](assets/images/settings/mqtt_settings.png "MQTT Settings") + + +### MQTT Settings + +##### HASP Node Name +The *Node Name* is the unique identifier of your device on your MQTT Broker. + +For example, setting the *Node Name* to **plate35** will make the device listen and communicate on the main topic **hasp/plate35/** + +##### Group Name +The *Group Name* is the unique identifier for a **Group** of devices. + +For example, the default *Group Name* is **plates**. This will make all devices in this group listen on the main topic **hasp/plates/** +This way you can send a command to all devices in the group at the same moment. Each devices will only respond on their own main *Node Name* topic. + +##### MQTT Broker +Set the IP or hostname of your MQTT Broker + +##### MQTT Port +Set the port for your MQTT Broker + +##### MQTT User and Password +Enter credentials if your *MQTT Broker* requires a Username and Password. + +--- + +Click 'Save Settings' to save you settings to the device. A restart is required to make the settings active. Navigate back to the Main Menu and click Restart to activate the settings. + + +## Commandline + +You can also configure the mqtt settings via the serial or telnet console: + +```bash +hostname myPlateName +mqtthost 192.168.0.123 +mqttport 1883 +mqttuser myUsername +mqttpass myPassword +reboot +``` \ No newline at end of file diff --git a/docs/Configuration/33-hasp.md b/docs/Configuration/33-hasp.md new file mode 100644 index 00000000..a309d199 --- /dev/null +++ b/docs/Configuration/33-hasp.md @@ -0,0 +1,40 @@ + +## HASP interface + +You can configure the general look and feel for the interface by uploading you favorite fonts and selecting your favorite theme and color. + +![HASP Settings](assets/images/settings/hasp_settings.png "HASP Settings") + +### HASP Settings + +##### Upload + +With the upload function you can upload 2 types of files + * .jsonl + This file contains the layout for the pages + See 'pages' section for more information on this file + * .zi + These are font files used in the Nextion/TJC HMI disp. + +##### UI Theme and Hue + +Select one of the built-in themes to select the general style for the HASP interface. +With the Hue slider you can select the base color for the built-in theme. + +##### Startup layout + +Enter the filename of the .jsonl you have uploaded to enables the layout on startup. + +##### Startup Page + +Select to what page the display should switch on startup. + +##### Startup brightness + +Select the brightness level of the display on startup. +*Please note that the display must support dim feature and GPIO for dim is set in display setup.* + +--- + +Click 'Save Settings' to save you settings to the device. A restart is required to make the settings active. Navigate back to the Main Menu and click Restart to activate the settings. + diff --git a/docs/Configuration/34-wifi.md b/docs/Configuration/34-wifi.md new file mode 100644 index 00000000..fbfe3fe6 --- /dev/null +++ b/docs/Configuration/34-wifi.md @@ -0,0 +1,31 @@ + +## Wifi + +When using a wireless network adapter, you need to configure the SSID to connect. + +![HASP Settings](assets/images/settings/wifi_settings.png "Wifi Settings") + +### Wifi Settings + +#### SSID + +The name of the access point to connect to. + +#### Password + +Optional password for the access point, if required. + +--- + +Click 'Save Settings' to save you settings to the device. A restart is required to make the settings active. Navigate back to the Main Menu and click Restart to activate the settings. + + +## Commandline + +You can also configure the wifi settings via the serial or telnet console: + +```bash +ssid myAccessPointName +pass myWifiPassword +reboot +``` \ No newline at end of file diff --git a/docs/Configuration/35-display.md b/docs/Configuration/35-display.md new file mode 100644 index 00000000..6ea2a238 --- /dev/null +++ b/docs/Configuration/35-display.md @@ -0,0 +1,39 @@ +## Display + +You can configure the general look and feel for the interface by uploading you favorite fonts and selecting your favorite theme and color. + +![HASP Settings](assets/images/settings/hasp_settings.png "HASP Settings") + +### HASP Settings + +##### Upload + +With the upload function you can upload 2 types of files + * .jsonl + This file contains the layout for the pages + See 'pages' section for more information on this file + * .zi + These are font files used in the Nextion/TJC HMI disp. + +##### UI Theme and Hue + +Select one of the built-in themes to select the general style for the HASP interface. +With the Hue slider you can select the base color for the built-in theme. + +##### Startup layout + +Enter the filename of the .jsonl you have uploaded to enables the layout on startup. + +##### Startup Page + +Select to what page the display should switch on startup. + +##### Startup brightness + +Select the brightness level of the display on startup. +*Please note that the display must support dim feature and GPIO for dim is set in display setup.* + +--- + +Click 'Save Settings' to save you settings to the device. A restart is required to make the settings active. Navigate back to the Main Menu and click Restart to activate the settings. + diff --git a/docs/Configuration/36-gpio.md b/docs/Configuration/36-gpio.md new file mode 100644 index 00000000..fb8596cc --- /dev/null +++ b/docs/Configuration/36-gpio.md @@ -0,0 +1,40 @@ + +## GPIO + +You can configure the general look and feel for the interface by uploading you favorite fonts and selecting your favorite theme and color. + +![HASP Settings](assets/images/settings/hasp_settings.png "HASP Settings") + +### HASP Settings + +##### Upload + +With the upload function you can upload 2 types of files + * .jsonl + This file contains the layout for the pages + See 'pages' section for more information on this file + * .zi + These are font files used in the Nextion/TJC HMI disp. + +##### UI Theme and Hue + +Select one of the built-in themes to select the general style for the HASP interface. +With the Hue slider you can select the base color for the built-in theme. + +##### Startup layout + +Enter the filename of the .jsonl you have uploaded to enables the layout on startup. + +##### Startup Page + +Select to what page the display should switch on startup. + +##### Startup brightness + +Select the brightness level of the display on startup. +*Please note that the display must support dim feature and GPIO for dim is set in display setup.* + +--- + +Click 'Save Settings' to save you settings to the device. A restart is required to make the settings active. Navigate back to the Main Menu and click Restart to activate the settings. + diff --git a/docs/Configuration/37-debug.md b/docs/Configuration/37-debug.md new file mode 100644 index 00000000..a0f00900 --- /dev/null +++ b/docs/Configuration/37-debug.md @@ -0,0 +1,40 @@ + +## Debug + +You can configure the general look and feel for the interface by uploading you favorite fonts and selecting your favorite theme and color. + +![HASP Settings](assets/images/settings/hasp_settings.png "HASP Settings") + +### HASP Settings + +##### Upload + +With the upload function you can upload 2 types of files + * .jsonl + This file contains the layout for the pages + See 'pages' section for more information on this file + * .zi + These are font files used in the Nextion/TJC HMI disp. + +##### UI Theme and Hue + +Select one of the built-in themes to select the general style for the HASP interface. +With the Hue slider you can select the base color for the built-in theme. + +##### Startup layout + +Enter the filename of the .jsonl you have uploaded to enables the layout on startup. + +##### Startup Page + +Select to what page the display should switch on startup. + +##### Startup brightness + +Select the brightness level of the display on startup. +*Please note that the display must support dim feature and GPIO for dim is set in display setup.* + +--- + +Click 'Save Settings' to save you settings to the device. A restart is required to make the settings active. Navigate back to the Main Menu and click Restart to activate the settings. + diff --git a/docs/Configuration/_sidebar.md b/docs/Configuration/_sidebar.md new file mode 100644 index 00000000..8588aea3 --- /dev/null +++ b/docs/Configuration/_sidebar.md @@ -0,0 +1,10 @@ +<!-- docs/_sidebar.md --> + +- **Configuration** +- [HTTP](./configuration/30-http.md) +- [MQTT](./configuration/32-mqtt.md) +- [HASP](./configuration/33-hasp.md) +- [Wifi](./configuration/34-wifi.md) +- [Display](./configuration/35-display.md) +- [GPIO](./configuration/36-gpio.md) +- [Debug](./configuration/37-debug.md) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..30d74d25 --- /dev/null +++ b/docs/README.md @@ -0,0 +1 @@ +test \ No newline at end of file diff --git a/docs/_navbar.md b/docs/_navbar.md new file mode 100644 index 00000000..dd3d757a --- /dev/null +++ b/docs/_navbar.md @@ -0,0 +1,23 @@ +<!-- _navbar.md --> + +* Getting started + + * [Quick start](quickstart.md) + * [Writing more pages](more-pages.md) + * [Custom navbar](custom-navbar.md) + * [Cover page](cover.md) + +* Objects + * [Button](13-objects?id=button) + * [Checkbox](13-objects?id=checkbox) + * [Text Label](13-objects?id=text-label) + * [Arc](13-objects?id=arc) + * [Colorwheel](13-objects?id=colorwheel) + * [Slider](13-objects?id=slider) + * [Double Slider](13-objects?id=double-slider) + * [Gauge](13-objects?id=gauge) + * [Progressbar](13-objects?id=progressbar) + * [Switch](13-objects?id=switch) + * [LED Indicator](13-objects?id=led-indicator) + * [Dropdown List](13-objects?id=dropdown-list) + * [Roller](13-objects?id=roller) \ No newline at end of file diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 00000000..f11f65b3 --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,23 @@ +<!-- docs/_sidebar.md --> + +- **Getting Started** +- [Hardware](./01-hardware.md) +- [Firmware Install](./02-installation.md) +- [Initial Setup](./03-wifi-setup.md) + +- **Usage** +- [Command Reference](./05-commands.md) +- [Frequently Asked Questions](./06-faq.md) + +- **Design Pages** +- [Pages](./12-pages.md) +- [Objects](./13-objects.md) +- [Styling](./14-styling.md) + +- **Demo Layouts** +- [Example Pages](./15-example-pages.md) + +- **Firmware Updates** +- [ESP32](./38-firmware-esp.md) +- [ESP8266](./38-firmware-esp.md) +- [STM32F4xx](./39-firmware-stm32.md) diff --git a/docs/assets/css/prism-xonokai.css b/docs/assets/css/prism-xonokai.css new file mode 100644 index 00000000..8cdceb5d --- /dev/null +++ b/docs/assets/css/prism-xonokai.css @@ -0,0 +1,189 @@ +/** +* xonokai theme for JavaScript, CSS and HTML +* based on: https://github.com/MoOx/sass-prism-theme-base by Maxime Thirouin ~ MoOx --> http://moox.fr/ , which is Loosely based on Monokai textmate theme by http://www.monokai.nl/ +* license: MIT; http://moox.mit-license.org/ +*/ +code[class*="language-"], +pre[class*="language-"] { + -moz-tab-size: 2; + -o-tab-size: 2; + tab-size: 2; + -webkit-hyphens: none; + -moz-hyphens: none; + -ms-hyphens: none; + hyphens: none; + white-space: pre; + white-space: pre-wrap; + word-wrap: normal; + font-family: Menlo, Monaco, "Courier New", monospace; + font-size: 14px; + color: #76d9e6; + text-shadow: none; +} + +pre > code[class*="language-"] { + font-size: 1em; +} + +pre[class*="language-"], +:not(pre) > code[class*="language-"] { + background: #2a2a2a; +} + +pre[class*="language-"] { + padding: 15px; + border-radius: 4px; + border: 1px solid #e1e1e8; + overflow: auto; + position: relative; +} + +pre[class*="language-"] code { + white-space: pre; + display: block; +} + +:not(pre) > code[class*="language-"] { + padding: 0.15em 0.2em 0.05em; + border-radius: .3em; + border: 0.13em solid #7a6652; + box-shadow: 1px 1px 0.3em -0.1em #000 inset; +} + +.token.namespace { + opacity: .7; +} + +.token.comment, +.token.prolog, +.token.doctype, +.token.cdata { + color: #6f705e; +} + +.token.operator, +.token.boolean, +.token.number { + color: #a77afe; +} + +.token.attr-name, +.token.string { + color: #e6d06c; +} + +.token.entity, +.token.url, +.language-css .token.string, +.style .token.string { + color: #e6d06c; +} + +.token.selector, +.token.inserted { + color: #a6e22d; +} + +.token.atrule, +.token.attr-value, +.token.keyword, +.token.important, +.token.deleted { + color: #ef3b7d; +} + +.token.regex, +.token.statement { + color: #76d9e6; +} + +.token.placeholder, +.token.variable { + color: #fff; +} + +.token.important, +.token.statement, +.token.bold { + font-weight: bold; +} + +.token.punctuation { + color: #bebec5; +} + +.token.entity { + cursor: help; +} + +.token.italic { + font-style: italic; +} + +code.language-markup { + color: #f9f9f9; +} + +code.language-markup .token.tag { + color: #ef3b7d; +} + +code.language-markup .token.attr-name { + color: #a6e22d; +} + +code.language-markup .token.attr-value { + color: #e6d06c; +} + +code.language-markup .token.style, +code.language-markup .token.script { + color: #76d9e6; +} + +code.language-markup .token.script .token.keyword { + color: #76d9e6; +} + +/* Line highlight plugin */ +pre[class*="language-"][data-line] { + position: relative; + padding: 1em 0 1em 3em; +} + +pre[data-line] .line-highlight { + position: absolute; + left: 0; + right: 0; + padding: 0; + margin-top: 1em; + background: rgba(255, 255, 255, 0.08); + pointer-events: none; + line-height: inherit; + white-space: pre; +} + +pre[data-line] .line-highlight:before, +pre[data-line] .line-highlight[data-end]:after { + content: attr(data-start); + position: absolute; + top: .4em; + left: .6em; + min-width: 1em; + padding: 0.2em 0.5em; + background-color: rgba(255, 255, 255, 0.4); + color: black; + font: bold 65%/1 sans-serif; + height: 1em; + line-height: 1em; + text-align: center; + border-radius: 999px; + text-shadow: none; + box-shadow: 0 1px 1px rgba(255, 255, 255, 0.7); +} + +pre[data-line] .line-highlight[data-end]:after { + content: attr(data-end); + top: auto; + bottom: .4em; +} diff --git a/docs/assets/images/faq/faq_file_browser.png b/docs/assets/images/faq/faq_file_browser.png new file mode 100644 index 00000000..bfacf31a Binary files /dev/null and b/docs/assets/images/faq/faq_file_browser.png differ diff --git a/docs/assets/images/faq/faq_file_delete.png b/docs/assets/images/faq/faq_file_delete.png new file mode 100644 index 00000000..099de13b Binary files /dev/null and b/docs/assets/images/faq/faq_file_delete.png differ diff --git a/docs/assets/images/hasp/header-small.png b/docs/assets/images/hasp/header-small.png new file mode 100644 index 00000000..f14f44da Binary files /dev/null and b/docs/assets/images/hasp/header-small.png differ diff --git a/docs/assets/images/hasp/header.png b/docs/assets/images/hasp/header.png new file mode 100644 index 00000000..1874a037 Binary files /dev/null and b/docs/assets/images/hasp/header.png differ diff --git a/docs/assets/images/hasp/oobe_setup.png b/docs/assets/images/hasp/oobe_setup.png new file mode 100644 index 00000000..a5b5db6e Binary files /dev/null and b/docs/assets/images/hasp/oobe_setup.png differ diff --git a/docs/assets/images/hasp/touch_calibration.png b/docs/assets/images/hasp/touch_calibration.png new file mode 100644 index 00000000..f7269c44 Binary files /dev/null and b/docs/assets/images/hasp/touch_calibration.png differ diff --git a/docs/assets/images/hasp/wifi_setup.png b/docs/assets/images/hasp/wifi_setup.png new file mode 100644 index 00000000..db33a0d1 Binary files /dev/null and b/docs/assets/images/hasp/wifi_setup.png differ diff --git a/docs/assets/images/objects/lv_ex_bar_1.png b/docs/assets/images/objects/lv_ex_bar_1.png new file mode 100644 index 00000000..19e8cf94 Binary files /dev/null and b/docs/assets/images/objects/lv_ex_bar_1.png differ diff --git a/docs/assets/images/objects/lv_ex_btn_1.png b/docs/assets/images/objects/lv_ex_btn_1.png new file mode 100644 index 00000000..3ebea06d Binary files /dev/null and b/docs/assets/images/objects/lv_ex_btn_1.png differ diff --git a/docs/assets/images/objects/lv_ex_checkbox_1.png b/docs/assets/images/objects/lv_ex_checkbox_1.png new file mode 100644 index 00000000..e57afa59 Binary files /dev/null and b/docs/assets/images/objects/lv_ex_checkbox_1.png differ diff --git a/docs/assets/images/objects/lv_ex_cont_1.png b/docs/assets/images/objects/lv_ex_cont_1.png new file mode 100644 index 00000000..c819f3d0 Binary files /dev/null and b/docs/assets/images/objects/lv_ex_cont_1.png differ diff --git a/docs/assets/images/objects/lv_ex_cpicker_1.png b/docs/assets/images/objects/lv_ex_cpicker_1.png new file mode 100644 index 00000000..17b959e7 Binary files /dev/null and b/docs/assets/images/objects/lv_ex_cpicker_1.png differ diff --git a/docs/assets/images/objects/lv_ex_dropdown_1.png b/docs/assets/images/objects/lv_ex_dropdown_1.png new file mode 100644 index 00000000..8dbd5e14 Binary files /dev/null and b/docs/assets/images/objects/lv_ex_dropdown_1.png differ diff --git a/docs/assets/images/objects/lv_ex_gauge_1.png b/docs/assets/images/objects/lv_ex_gauge_1.png new file mode 100644 index 00000000..aebc774f Binary files /dev/null and b/docs/assets/images/objects/lv_ex_gauge_1.png differ diff --git a/docs/assets/images/objects/lv_ex_label_1.png b/docs/assets/images/objects/lv_ex_label_1.png new file mode 100644 index 00000000..593cf623 Binary files /dev/null and b/docs/assets/images/objects/lv_ex_label_1.png differ diff --git a/docs/assets/images/objects/lv_ex_led_1.png b/docs/assets/images/objects/lv_ex_led_1.png new file mode 100644 index 00000000..4627b6eb Binary files /dev/null and b/docs/assets/images/objects/lv_ex_led_1.png differ diff --git a/docs/assets/images/objects/lv_ex_linemeter_1.png b/docs/assets/images/objects/lv_ex_linemeter_1.png new file mode 100644 index 00000000..6d422fbc Binary files /dev/null and b/docs/assets/images/objects/lv_ex_linemeter_1.png differ diff --git a/docs/assets/images/objects/lv_ex_page_1.png b/docs/assets/images/objects/lv_ex_page_1.png new file mode 100644 index 00000000..6c4d7c24 Binary files /dev/null and b/docs/assets/images/objects/lv_ex_page_1.png differ diff --git a/docs/assets/images/objects/lv_ex_roller_1.png b/docs/assets/images/objects/lv_ex_roller_1.png new file mode 100644 index 00000000..c1ef2db3 Binary files /dev/null and b/docs/assets/images/objects/lv_ex_roller_1.png differ diff --git a/docs/assets/images/objects/lv_ex_slider_1.png b/docs/assets/images/objects/lv_ex_slider_1.png new file mode 100644 index 00000000..0140cf36 Binary files /dev/null and b/docs/assets/images/objects/lv_ex_slider_1.png differ diff --git a/docs/assets/images/objects/lv_ex_spinner_1.png b/docs/assets/images/objects/lv_ex_spinner_1.png new file mode 100644 index 00000000..7faf0d30 Binary files /dev/null and b/docs/assets/images/objects/lv_ex_spinner_1.png differ diff --git a/docs/assets/images/objects/lv_ex_switch_1.png b/docs/assets/images/objects/lv_ex_switch_1.png new file mode 100644 index 00000000..0365538d Binary files /dev/null and b/docs/assets/images/objects/lv_ex_switch_1.png differ diff --git a/docs/assets/images/objects/lv_ex_tabview_1.png b/docs/assets/images/objects/lv_ex_tabview_1.png new file mode 100644 index 00000000..c556567a Binary files /dev/null and b/docs/assets/images/objects/lv_ex_tabview_1.png differ diff --git a/docs/assets/images/settings/configuration.png b/docs/assets/images/settings/configuration.png new file mode 100644 index 00000000..f683a66e Binary files /dev/null and b/docs/assets/images/settings/configuration.png differ diff --git a/docs/assets/images/settings/debug_settings.png b/docs/assets/images/settings/debug_settings.png new file mode 100644 index 00000000..54a68492 Binary files /dev/null and b/docs/assets/images/settings/debug_settings.png differ diff --git a/docs/assets/images/settings/gui_settings.png b/docs/assets/images/settings/gui_settings.png new file mode 100644 index 00000000..1dead791 Binary files /dev/null and b/docs/assets/images/settings/gui_settings.png differ diff --git a/docs/assets/images/settings/hasp_settings.png b/docs/assets/images/settings/hasp_settings.png new file mode 100644 index 00000000..39e78090 Binary files /dev/null and b/docs/assets/images/settings/hasp_settings.png differ diff --git a/docs/assets/images/settings/mqtt_settings.png b/docs/assets/images/settings/mqtt_settings.png new file mode 100644 index 00000000..334b11cb Binary files /dev/null and b/docs/assets/images/settings/mqtt_settings.png differ