You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository has been archived by the owner on Jun 15, 2021. It is now read-only.
AsciiDoc is a pleasure to write in, but Asciidoctor is drastically limited in format and features—it's just a big wall of text, no matter what. Most notably, there is no way to provide search, and no way to adjust the UI without tons of work.
Instead of wrestling with this limited framework, it makes more sense to me to consider migrating to another framework that's more flexible and feature-rich from the start.
I don't have any specific ideas at the moment, and I don't think this is an urgent priority, but as we have more docs over the next few months (roles docs in particular), the front page will start to get unwieldy.
Therefore I'm creating this issue as a starting point for suggestions and consideration, so that more concrete action can be taken in the next 5-7 months (probably after making a more specific proposal in bisq-network/proposals once details are known).
I'm experimenting with integrating docs into the website through a Jekyll plugin called jekyll-asciidoc.
Benefits:
gain ability to implement features like search, translations, and better navigation
can continue writing in AsciiDoc
no need to learn and maintain a new framework (VuePress, Antara, etc)
we already maintain a Jekyll site
harness the traffic and SEO of the main Bisq site
My initial integration of content went well. The following remains:
implementing search (lunr.js looks promising; it accomplishes search by generating an index at build time that's sent to clients and queried right in the browser)
determining a navigation layout that combines site navigation with docs navigation that's not unwieldy (have ideas and mockups)
having a plan for translations (should be able to use the existing translations mechanism combined with asciidoc attributes)
More importantly, we need to decide if this integration is a good idea from an organizational standpoint, since the website and docs maintainers have historically been different roles, and this integration would effectively put both repositories under the control of one role.
I want to get other docs done before spending more time on this, so I make this update in search of feedback, with the intention of revisiting it in a month or so to implement.
AsciiDoc is a pleasure to write in, but Asciidoctor is drastically limited in format and features—it's just a big wall of text, no matter what. Most notably, there is no way to provide search, and no way to adjust the UI without tons of work.
Instead of wrestling with this limited framework, it makes more sense to me to consider migrating to another framework that's more flexible and feature-rich from the start.
I don't have any specific ideas at the moment, and I don't think this is an urgent priority, but as we have more docs over the next few months (roles docs in particular), the front page will start to get unwieldy.
Therefore I'm creating this issue as a starting point for suggestions and consideration, so that more concrete action can be taken in the next 5-7 months (probably after making a more specific proposal in bisq-network/proposals once details are known).
cc #128
The text was updated successfully, but these errors were encountered: