From 48fb647c164cb5857351a98b4beae18f25a1d2cd Mon Sep 17 00:00:00 2001 From: Zachary Klosko Date: Sun, 7 Jun 2020 13:23:26 -0400 Subject: [PATCH] Fixing toc for github pages --- docs/_config.yml | 3 +- docs/_data/nav.yml | 6 +- docs/_includes/toc.html | 112 ++++++++++++++++++++++++++++++++ docs/_layouts/docs.html | 6 +- docs/_layouts/page.html | 30 --------- docs/_layouts/splash.html | 1 - docs/contribute.md | 2 +- docs/css/creative.min.css | 6 +- docs/freeipa.md | 2 +- docs/host-configuration.md | 1 - docs/icecast-shoutcast.md | 2 +- docs/interface-customization.md | 2 +- docs/library.md | 2 +- docs/live-broadcast.md | 2 +- docs/playlists-smartblocks.md | 2 +- docs/playout-history.md | 2 +- docs/podcasts-webstreams.md | 2 +- docs/preparing-media.md | 4 +- docs/preparing-the-server.md | 2 +- docs/quickstart.md | 2 +- docs/reverse-proxy.md | 2 +- docs/setting-the-server-time.md | 2 +- docs/settings.md | 2 +- docs/ssl-config.md | 2 +- docs/troubleshooting.md | 27 ++++---- docs/upgrading.md | 2 +- docs/users.md | 2 +- docs/vagrant.md | 4 +- 28 files changed, 155 insertions(+), 79 deletions(-) create mode 100644 docs/_includes/toc.html delete mode 100644 docs/_layouts/page.html diff --git a/docs/_config.yml b/docs/_config.yml index bd7a7c791..50d035a7f 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -6,6 +6,7 @@ url: "" # The base hostname & protocol for your site, e.g. http://example.com layouts_dir: _layouts data_dir: _data +includes_dir: _includes favicon: favicon.ico @@ -19,4 +20,4 @@ headbuttontext: Get LibreTime # Build settings plugins: - - jekyll-toc \ No newline at end of file + - kramdown \ No newline at end of file diff --git a/docs/_data/nav.yml b/docs/_data/nav.yml index 053f464f1..ee405d9cf 100644 --- a/docs/_data/nav.yml +++ b/docs/_data/nav.yml @@ -1,8 +1,6 @@ topnav: -- page: Introduction - url: index - page: Docs - url: scheduling-shows + url: quickstart - page: Github url: https://github.com/LibreTime/libretime - page: Sponsor @@ -13,6 +11,8 @@ docsnav: contents: - page: 1. Quick Install url: quickstart + - page: 1.1 Reverse Proxy + url: reverse-proxy - page: 2. Host Configuration url: host-configuration - page: 3. Setting the Server Time diff --git a/docs/_includes/toc.html b/docs/_includes/toc.html new file mode 100644 index 000000000..509015625 --- /dev/null +++ b/docs/_includes/toc.html @@ -0,0 +1,112 @@ +{% capture tocWorkspace %} + {% comment %} + Version 1.0.12 + https://github.com/allejo/jekyll-toc + + "...like all things liquid - where there's a will, and ~36 hours to spare, there's usually a/some way" ~jaybe + + Usage: + {% include toc.html html=content sanitize=true class="inline_toc" id="my_toc" h_min=2 h_max=3 %} + + Parameters: + * html (string) - the HTML of compiled markdown generated by kramdown in Jekyll + + Optional Parameters: + * sanitize (bool) : false - when set to true, the headers will be stripped of any HTML in the TOC + * class (string) : '' - a CSS class assigned to the TOC + * id (string) : '' - an ID to assigned to the TOC + * h_min (int) : 1 - the minimum TOC header level to use; any header lower than this value will be ignored + * h_max (int) : 6 - the maximum TOC header level to use; any header greater than this value will be ignored + * ordered (bool) : false - when set to true, an ordered list will be outputted instead of an unordered list + * item_class (string) : '' - add custom class(es) for each list item; has support for '%level%' placeholder, which is the current heading level + * baseurl (string) : '' - add a base url to the TOC links for when your TOC is on another page than the actual content + * anchor_class (string) : '' - add custom class(es) for each anchor element + * skipNoIDs (bool) : false - skip headers that do not have an `id` attribute + + Output: + An ordered or unordered list representing the table of contents of a markdown block. This snippet will only + generate the table of contents and will NOT output the markdown given to it + {% endcomment %} + + {% capture my_toc %}{% endcapture %} + {% assign orderedList = include.ordered | default: false %} + {% assign skipNoIDs = include.skipNoIDs | default: false %} + {% assign minHeader = include.h_min | default: 1 %} + {% assign maxHeader = include.h_max | default: 6 %} + {% assign nodes = include.html | split: ' maxHeader %} + {% continue %} + {% endif %} + + {% assign _workspace = node | split: '' | first }}>{% endcapture %} + {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %} + + {% assign indentAmount = headerLevel | minus: minHeader %} + {% assign space = '' %} + {% for i in (1..indentAmount) %} + {% assign space = space | prepend: ' ' %} + {% endfor %} + + {% if include.item_class and include.item_class != blank %} + {% capture listItemClass %}{:.{{ include.item_class | replace: '%level%', headerLevel }}}{% endcapture %} + {% endif %} + + {% capture anchor_body %}{% if include.sanitize %}{{ header | strip_html }}{% else %}{{ header }}{% endif %}{% endcapture %} + {% capture anchor_body %}{{ anchor_body | replace: "|", "\|" }}{% endcapture %} + + {% if html_id %} + {% capture list_item %}[{{ anchor_body }}]({% if include.baseurl %}{{ include.baseurl }}{% endif %}#{{ html_id }}){% endcapture %} + {% else %} + {% capture list_item %}{{ anchor_body }}{% endcapture %} + {% endif %} + + {% capture my_toc %}{{ my_toc }} +{{ space }}{{ listModifier }} {{ listItemClass }} {{ list_item }}{% if include.anchor_class %}{:.{{ include.anchor_class }}}{% endif %}{% endcapture %} + {% endfor %} + + {% if include.class and include.class != blank %} + {% capture my_toc %}{:.{{ include.class }}} +{{ my_toc | lstrip }}{% endcapture %} + {% endif %} + + {% if include.id %} + {% capture my_toc %}{: #{{ include.id }}} +{{ my_toc | lstrip }}{% endcapture %} + {% endif %} +{% endcapture %}{% assign tocWorkspace = '' %}{{ my_toc | markdownify | strip }} diff --git a/docs/_layouts/docs.html b/docs/_layouts/docs.html index ab16b6033..a2c0b9bdd 100644 --- a/docs/_layouts/docs.html +++ b/docs/_layouts/docs.html @@ -83,12 +83,10 @@ layout: default

{{ page.title }}

-
- {% toc %} -
-
+
{% include toc.html html=content class=toc ordered=true %}
+
{{ content }}
diff --git a/docs/_layouts/page.html b/docs/_layouts/page.html deleted file mode 100644 index 9abe62933..000000000 --- a/docs/_layouts/page.html +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: default ---- - - - - - - - -
-
-
-
-

{{ page.title }}

-
-

- {{ page.blurb }} -

-
-
-
-
- - {{ content }} - - - diff --git a/docs/_layouts/splash.html b/docs/_layouts/splash.html index 1c856a170..c01ac39a9 100644 --- a/docs/_layouts/splash.html +++ b/docs/_layouts/splash.html @@ -79,7 +79,6 @@ {{ site.headsubtext}}

{{ site.headbuttontext }} - Read the Docs diff --git a/docs/contribute.md b/docs/contribute.md index adddc8fef..92fb6042d 100644 --- a/docs/contribute.md +++ b/docs/contribute.md @@ -1,7 +1,7 @@ --- layout: docs title: Contributing to LibreTime -toc: true + --- > LibreTime is a fork of AirTime due to stalled development of the FLOSS version. For background on this, diff --git a/docs/css/creative.min.css b/docs/css/creative.min.css index ee314e53a..f71c50613 100755 --- a/docs/css/creative.min.css +++ b/docs/css/creative.min.css @@ -320,10 +320,10 @@ padding: 10px 20px; } /* TOC */ -.section-nav { +.toc { background-color: #fff; - margin: 5px 0; - padding: 10px 30px; + margin: 0px 0; + padding: 10px 0px; border: 1px solid #212529; border-radius: 0px; border-left: 10px solid #212529; diff --git a/docs/freeipa.md b/docs/freeipa.md index d450c44e7..8da159d68 100644 --- a/docs/freeipa.md +++ b/docs/freeipa.md @@ -1,7 +1,7 @@ --- layout: docs title: FreeIPA Configuration -toc: true + --- You can configure LibreTime to delegate all authentication to a FreeIPA server. diff --git a/docs/host-configuration.md b/docs/host-configuration.md index bb4d3a48f..6cd1910b5 100644 --- a/docs/host-configuration.md +++ b/docs/host-configuration.md @@ -1,7 +1,6 @@ --- layout: docs title: Host configuration -toc: true --- The streaming host configuration for LibreTime is shown in the file */etc/airtime/liquidsoap.cfg* which is automatically generated by the **Streams** page, found on the **System** menu of the LibreTime administration interface. For this reason, you would not normally edit the streaming configuration manually, as any changes are likely to be overwritten by the administration interface. diff --git a/docs/icecast-shoutcast.md b/docs/icecast-shoutcast.md index 97a486bc5..39f92b111 100644 --- a/docs/icecast-shoutcast.md +++ b/docs/icecast-shoutcast.md @@ -1,7 +1,7 @@ --- layout: docs title: Icecast and Shoutcast Stream Configuration -toc: true + --- LibreTime supports direct connection to two popular streaming media servers, the open source **Icecast** () and the proprietary **SHOUTcast** (). Apart from the software license, the main difference between these two servers is that Icecast supports simultaneous MP3, AAC, Ogg Vorbis or Ogg Opus streaming from LibreTime, whereas SHOUTcast supports MP3 and AAC streams but not Ogg Vorbis or Opus. The royalty-free Ogg Vorbis format has the advantage of better sound quality than MP3 at lower bitrates, which has a direct impact on the amount of bandwidth that your station will require to serve the same number of listeners. Ogg Opus also benefits from good sound quality at low bitrates, with the added advantage of lower latency than other streaming formats. Opus is now an IETF standard () and requires Icecast 2.4 or later to be installed on the streaming server. diff --git a/docs/interface-customization.md b/docs/interface-customization.md index b48e181e0..f5972d519 100644 --- a/docs/interface-customization.md +++ b/docs/interface-customization.md @@ -1,7 +1,7 @@ --- layout: docs title: Modifying the LibreTime interface -toc: true + --- diff --git a/docs/library.md b/docs/library.md index 7a95bb750..d52d6c5e2 100644 --- a/docs/library.md +++ b/docs/library.md @@ -1,7 +1,7 @@ --- layout: docs title: Dashboard and Calendar -toc: true + --- # Dashboard {#dashboard} diff --git a/docs/live-broadcast.md b/docs/live-broadcast.md index 78abb49e8..764d5864f 100644 --- a/docs/live-broadcast.md +++ b/docs/live-broadcast.md @@ -1,7 +1,7 @@ --- layout: docs title: Broadcasting live with MIXXX or B.U.T.T. -toc: true + --- This how to is intended for DJs using BUTT or MIXXX to stream to their LibreTime diff --git a/docs/playlists-smartblocks.md b/docs/playlists-smartblocks.md index 67f9c771f..fcf35855e 100644 --- a/docs/playlists-smartblocks.md +++ b/docs/playlists-smartblocks.md @@ -1,7 +1,7 @@ --- layout: docs title: Playlists and Smartblocks -toc: true + --- # Playlists {#playlists} diff --git a/docs/playout-history.md b/docs/playout-history.md index f5773a853..ff4076ef3 100644 --- a/docs/playout-history.md +++ b/docs/playout-history.md @@ -1,7 +1,7 @@ --- layout: docs title: Playout History -toc: true + --- # History {#history} diff --git a/docs/podcasts-webstreams.md b/docs/podcasts-webstreams.md index 29e9ae846..082b1ae32 100644 --- a/docs/podcasts-webstreams.md +++ b/docs/podcasts-webstreams.md @@ -1,7 +1,7 @@ --- layout: docs title: Podcasts and Webstreams -toc: true + --- diff --git a/docs/preparing-media.md b/docs/preparing-media.md index 8c10b1326..28fbd526b 100644 --- a/docs/preparing-media.md +++ b/docs/preparing-media.md @@ -1,7 +1,7 @@ --- layout: docs title: Preparing Media for LibreTime -toc: true + --- Before uploading media to an LibreTime server, there are a number of factors which should be considered. Getting your ingest workflow right will save you a lot of time later. @@ -92,6 +92,6 @@ In the output from vorbisgain, *Peak* is the maximum sample value of the file be Before importing media, it is good practice to check for any silent sections in the media files. While LibreTime compensates for leading and trailing silence with the use of automatic cue-in and cue-out points****, it may be preferable to trim these files to the intended length before upload. This is because media in the LibreTime library could potentially be re-used in many different systems. **Audacity** is a cross-platform editor suitable for the task of trimming audio files, available from [http://audacity.sourceforge.net/](http://audacity.sourceforge.net "http://sourceforge.net/projects/dr14tmeter/") -Very quiet introductions or over-long fades can also lead to apparent gaps in your broadcast playout. Some audio CDs feature a 'hidden track' at the end, which in fact uses a long period of silence within the final track, rather than an actual separate track on the disc. This means that CD encoding programs will often encode both the hidden material and the silence in the media file. For example, the track *Debra* from the CD *Midnite Vultures* by *Beck* includes hidden material preceded by seven minutes of silence, as shown in the screen shot from Audacity below. +Very quiet introductions or over-long fades can also lead to apparent gaps in your broadcast playout. Some audio CDs feature a 'hidden track' at the end, which in fact uses a long period of silence within the final track, rather than an actual separate track on the disc. This means that CD encoding programs will often encode both the hidden material and the silence in the media file. For example, the track "Debra" from the CD *Midnite Vultures* by Beck includes hidden material preceded by seven minutes of silence, as shown in the screen shot from Audacity below. ![](img/Screenshot126-Debra_silence.png) diff --git a/docs/preparing-the-server.md b/docs/preparing-the-server.md index 70e077740..207a0344a 100644 --- a/docs/preparing-the-server.md +++ b/docs/preparing-the-server.md @@ -137,7 +137,7 @@ ensure that your RabbitMQ configuration and user permissions are safe. ### RabbitMQ hostname RabbitMQ requires a fixed and resolvable hostname (see -[the docs](http://www.rabbitmq.com/ec2.html#issues-hostname)), which is normal +[the docs](http://www.rabbitmq.com/ec2.html#issues-hostname), which is normal for a server. For a desktop or laptop machine where the hostname changes frequently or is not resolvable, this issue may prevent RabbitMQ from starting. When using a desktop or laptop computer with a dynamic IP address, such as an diff --git a/docs/quickstart.md b/docs/quickstart.md index 6ad11d33d..1dcfa954d 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,7 +1,7 @@ --- title: Quick Install layout: docs -toc: true + --- > Note: this guide is assuming you are using Ubuntu 18.04 LTS for installation, which comes with `ufw` and `netplan`, diff --git a/docs/reverse-proxy.md b/docs/reverse-proxy.md index 981338773..3943accd4 100644 --- a/docs/reverse-proxy.md +++ b/docs/reverse-proxy.md @@ -1,7 +1,7 @@ --- layout: docs title: Reverse Proxy Connections -toc: true + --- In some deployments, the LibreTime server is deployed behind a reverse proxy, diff --git a/docs/setting-the-server-time.md b/docs/setting-the-server-time.md index 67037348d..071f59914 100644 --- a/docs/setting-the-server-time.md +++ b/docs/setting-the-server-time.md @@ -1,7 +1,7 @@ --- layout: docs title: Setting the Server Time -toc: true + --- # Setting the server time diff --git a/docs/settings.md b/docs/settings.md index 046f1f93e..1c5d2a6b4 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -1,7 +1,7 @@ --- layout: docs title: Settings -toc: true + --- diff --git a/docs/ssl-config.md b/docs/ssl-config.md index af4b0bf72..ae7c903d4 100644 --- a/docs/ssl-config.md +++ b/docs/ssl-config.md @@ -1,7 +1,7 @@ --- layout: docs title: Setting up SSL -toc: true + --- To increase the security of your server, you can enable encrypted access to the LibreTime administration interface, and direct your users towards this more secure login page. The main advantage of using this encryption is that your remote users' login names and passwords are not sent in plain text across the public Internet or untrusted local networks, such as shared Wi-Fi access points. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 67f9c5930..f1835ec48 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,7 +1,7 @@ --- layout: docs title: Troubleshooting -toc: true + --- LibreTime is effectively a web site running on a LAPP stack, so individual components of the system can be started, stopped, restarted or checked in the server console using the **systemctl** command: @@ -17,13 +17,11 @@ For example, to restart the Airtime playout engine, you could enter the command: sudo systemctl restart libretime-playout -Log files {#logs} ---------- +# Log files {#logs} Airtime stores log files under the directory path */var/log/airtime/* which can be useful for diagnosing the cause of any problems. Copies of these log files may be requested by LibreTime developers while they are providing technical support for your Airtime deployment. -Test tones {#tones} ----------- +# Test tones {#tones} If you need to test your computer's soundcard, you can use `speaker-test`, a tone generator for ALSA. This does not come installed with LibreTime but can be installed with `sudo apt install speaker-test`. @@ -53,20 +51,19 @@ Where: -h show help menu ``` -RabbitMQ hostname changes {#rabbitmq} -------------------------- +# RabbitMQ hostname changes If the Airtime logs indicate failures to connect to the RabbitMQ server, such as: +``` +2013-10-31 08:21:11,255 ERROR - [pypomessagehandler.py : main() : line +99] - Error connecting to RabbitMQ Server. Trying again in few seconds - 2013-10-31 08:21:11,255 ERROR - [pypomessagehandler.py : main() : line - 99] - Error connecting to RabbitMQ Server. Trying again in few seconds - - 2013-10-31 08:21:11,255 ERROR - \[pypomessagehandler.py : main() : line 99\] - Error connecting to RabbitMQ Server. Trying again in few seconds - See more at: http://forum.sourcefabric.org/discussion/16050/\#sthash.W8OJrNFm.dpuf - +2013-10-31 08:21:11,255 ERROR - \[pypomessagehandler.py : main() : line 99\] - Error connecting to RabbitMQ Server. Trying again in few seconds - See more at: http://forum.sourcefabric.org/discussion/16050/\#sthash.W8OJrNFm.dpuf +``` but the RabbitMQ server is running normally, this error might be due to a change in the server's hostname since Airtime installation. Directory names under */var/lib/rabbitmq/mnesia/* indicate that RabbitMQ's database files are organised according to the hostname of the server, for example: - - rabbit@airtime - +``` +rabbit@airtime +``` where the hostname is *airtime.example.com*. If the hostname has changed, it may be necessary to reconfigure RabbitMQ manually, as follows: 1. Delete the files in */var/lib/rabbitmq/mnesia/* diff --git a/docs/upgrading.md b/docs/upgrading.md index f2190b07e..54ed6556a 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -1,7 +1,7 @@ --- layout: docs title: Upgrading LibreTime -toc: true + --- ## LibreTime versioning diff --git a/docs/users.md b/docs/users.md index e5d696e72..d1913c183 100644 --- a/docs/users.md +++ b/docs/users.md @@ -1,7 +1,7 @@ --- layout: docs title: Managing Users -toc: true + --- > Note: if your Airtime server is accessible from the public Internet (ex. being hosted in a cloud VM) diff --git a/docs/vagrant.md b/docs/vagrant.md index 85e68ce7b..bd507a858 100644 --- a/docs/vagrant.md +++ b/docs/vagrant.md @@ -1,10 +1,10 @@ --- layout: page title: Using Vagrant and Virtualbox for developing LibreTime -toc: true + --- -> Prerequisites: git, [Vagrant](https://vagrantup.com), libvirt or VirturalBox +> Prerequisites: git, [Vagrant](https://vagrantup.com), libvirt or VirtualBox # VirtualBox