Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move documentation front-end from GitBook to vuepress #495

Closed
pavlenex opened this issue Apr 29, 2020 · 28 comments · Fixed by #516
Closed

Move documentation front-end from GitBook to vuepress #495

pavlenex opened this issue Apr 29, 2020 · 28 comments · Fixed by #516
Assignees

Comments

@pavlenex
Copy link
Contributor

@pavlenex pavlenex commented Apr 29, 2020

Current documentation front-end is hosted by GitBook. While this was fantastic and easy start for us which allowed us to have a quick nicely looking solution, the complexity of our documentation is growing. Unfortunately, the need for customization can't be done all via GitBook.

Here are current feature we're missing:

  • Make a design consistent with our design-guidelines
  • Multi-repository documentation

Multi-repo documentation

The multi-repo docs would allow us to have docker, transmuter or any other repository presented on the front-end while on-the back-end their documentation stays in the respective repositories. This makes maintainance of documentation easier, since the changes are made on the back-end of respective repo. For example, our docker documentation on the front-end is very brief, where as btcpay-docker is one of most extensive documentations we have. With multi-repo access we'll be able to render btcpay-docker without having to maintain a page for it in the docs.

Design consistency

Efforts to make BTCPay Server look like a coherent piece of software accross multiple platforms continues. We've already had people asking for for a dark mode of our docs, which with GitBook limitation is not possible.

Gitbook itself has advantages over VueJS for sure. They have an analytics and rating system, but to be honest we've never looked at that. Furthermore as a privacy orientated software, we don't really care about them. Perhaps a feedback system would be nice to have.

@dennisreimann will take a lead on this since he's helped Wasabi Documentation and has plenty of experience in this field. Of course, we will first test on forks to see if we can make it all work as we want.

If you have any suggestions please let us know. I'll leave it up to @dennisreimann to expand on other advantages that we get with vue.js.

For those interested into seeing vuepress in action here is a list of projects using it in different ways.
We've been recomended Agora as well, but it has a markdown language of it's own which would require an insane amount of modifications on our end, which is not what we want.

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented Apr 29, 2020

Alright, I've set up a fork and deployment, so that we can test everything and build a proof of concept for the steps involved:

  • General VuePress setup and docs migration
  • Multi-repo setup
    • Integration of and build for repos other than doc
    • Build triggers for the doc repo whenever a dependecy repo changes (or better yet, the docs in that repo)
  • Design adjustments
    • Integrate light/dark theme
    • Add theme switch
  • Improve video integration
  • Algolia integration
  • Migrate complete navigation and eventually adjust the structure (e.g. using subfolders)

After the migration

  • Setup and integrate all dependent repos and build triggers
  • Send PR for our Algolia config that has the correct selectors

One more thing I'd advise: Let's apply for Algolia for Open Source. Their search is great and easy to integrate into VuePress. From my experience it takes a while until they approve open source accounts, so let's just do that right away. Ok, @pavlenex?

Note: Right now only part of the navigation is converted, but what's there works for getting a feel for the basics. The configuration and public files (like images) are in the docs/.vuepress directory and here are the details of how to configure the site.

Feedback welcome!

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented Apr 30, 2020

Multi-repo build works and @Kukks set up a trigger for the btcTransmuter build which kicks off the main build via repository dispatch. (One thing we found out though: this only works for the master branch of the receiving repository)

repository-dispatch

The Docker and Transmuter docs appear last in the nav on the left right now -> Docs.

@pavlenex
Copy link
Contributor Author

@pavlenex pavlenex commented Apr 30, 2020

That's so freaking cool guys, fantastic work so far! I applied or Algolia that one should be done soonish.

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented May 4, 2020

Light/dark theme are integrated, need to add the theme switch to make it an explicit choice next :)

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented May 4, 2020

Added the theme switch (OMG is this nice 😍) and improved the video and image integration 👍

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented May 4, 2020

Videos are now lazy loaded on demand and played inline, which feels very nice imho.

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented May 4, 2020

And we have custom blocks like this one here with danger, warning, and tip:

warning

Reference for custom containers.

@pavlenex
Copy link
Contributor Author

@pavlenex pavlenex commented May 4, 2020

Thanks for making the videos load properly. It's been a nightmare to maintain and a terrible UX so far. Great work Dennis.

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented May 5, 2020

Updated the Algolia config and now the basic integration work. Nevertheless they configured it for the current docs.btcpayserver.org, that's why we should also send in a PR to update the config once we've merged and deployed the new version with the correct selectors. I've added a TODO for that.

@pavlenex Let's figure out the new structure next. This one is almost ready to go 🤟

@pavlenex
Copy link
Contributor Author

@pavlenex pavlenex commented May 5, 2020

With #501 in mind, I've been thinking quite a bit, and here's what I suggest. If something is unclear, let me know so I can elaborate on why something is structured that way.

Documentation

User Docs

Introduction

  • Introduction
  • Features
  • How it works

Basics

  • Use Case
  • BTCPay Server vs others
  • Try it Out

Deployment

  • Choosing a deployment method
  • Third-party hosting
  • Docker
    -- Web Deployment
    --- Configurator
    --- LunaNode
    -- Azure Deployment
    --- Azure pennypitnching gude
    -- Google Cloud Deployment
    -- Hardware deployment
    --- Raspberry Pi Deployment
    ---- Raspberry Pi 3 Deployment
    ---- Raspberry Pi 4 Deployment
    --- Advanced Hardware Deployment
    ----Dynamic DNS
    ----Reverse SSH Tunnel
    -- Docker Plugins
    --- Tranmsuter
    --- PiHole
  • Manual deployment
    --Manual deployment extended

Getting Started

  • (1) Register account
  • (2) Create a store
  • (3) Connect a wallet
    -- Connect a hardware wallet (Vault.md)
    --- Ledger
    --- ColdCard
    -- Connect a software wallet
    --- Electrum
    --- Wasabi
    -- Create a wallet
    --- Hot wallet
  • (4) What's Next?

Features

  • Apps
  • Wallet
  • Invoices
  • Payment Requests
  • Lightning Network
  • PayJoin (P2EP)
    -- Payjoin Specification

Integrations

-WooCommerce
-Drupal
-Magento
-PrestaShop
-Custom Integration

Support and community

-FAQ and common issues
--FAQ Table of Contents
--General FAQ
--Deployment FAQ
--Synchronization FAQ
--Integrations FAQ
--Server Settings FAQ
--Stores FAQ
--Wallet FAQ
--Apps FAQ
--Lightning Network FAQ
--Altcoins FAQ
-Troubleshooting an issue
-Support
-Contribute
-Translate
-Community

Dev Docs

  • API Docs
    -- New API
    -- Legacy API (BitPay)
  • Clients
    -Development
    -Architecture
    -Developing Locally
    -How to add an Altcoin
    -Customizing Themes
    -FAQ and common issues

A few notes:

  • It's not yet determine how we'll separate user and dev docs, most likely on the docs.btcpayserver.org we'll need to do different CTA discussion here
  • While I am very proud of what I did with Connect a wallet section, in reality it, for a full effect, derivation scheme re-structure in UI of BTCPay Server itself is needed.
  • Dev docs section is not at all final, it needs to be filled with docs from different clients we have
  • I was not sure if "Integrations" is user-doc or dev doc. I had same dilema for "deployment" but kinda felt it's user-doc, though some deployment methods may more be dev-docs.
  • Deployment section was a mess due to all of deployment methods being docker.
  • Added Docker plugins section where we can document third-party plugins like PiHole, Tranmsuter, etc @dennisreimann is is realistic to expect people that add plugins will allows us to automate deployments from their repo? How would that work?

Feedback is welcome of course, this is still not perfect, and needs actual docs re-works for it to take full effect.

@pavlenex
Copy link
Contributor Author

@pavlenex pavlenex commented May 5, 2020

@dennisreimann Just a side note,I'm personally not a fan of content:not(.custom) { max-width: 740px; it looks like a bit too much unused space. Not an expert on this, but I find existing docs easier to focus on while reading, at least on my 27 monitor.. Would be cool if we can get different iteration on that layout. Perhaps a sidebar could use some padding on the right as well.

existing docs
newdocs

Also the Edit This Page link at the bottom is broken. (Probably due to folders you use on your fork, so that's okay, I prefer we finally use folders as well)

@Kukks
Copy link
Member

@Kukks Kukks commented May 6, 2020

From a quick glance it looks good from my end

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented May 6, 2020

Added Docker plugins section where we can document third-party plugins like PiHole, Tranmsuter, etc @dennisreimann is is realistic to expect people that add plugins will allows us to automate deployments from their repo? How would that work?

We can pull and integrate their docs, but I would refrain from changes in their repos/docs triggering an update of our docs. The main reason for that is we'd need to provide a personal access token from an account of ours that has the permission to trigger the build. The permissions on GH aren't fine grained enough though, so that we'd hand out all kinds of permissions along with that …
Anyways, I don't think that this is a show stopper for the idea, beecause our docs should be building frequently (we could also set up a scheduled build like once daily, even though nothing changed) and worst case is that they'd have to request a new build once their docs changed.

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented May 6, 2020

Updated the structure according to your proposal and what we discussed in the chat – let me know if I got something wrong or what needs further changing :)

The update also sets a maximum width for the wraper and centers the page if the browser is more than 1280px wide.

Mobile navbar is also fixed now.

@pavlenex
Copy link
Contributor Author

@pavlenex pavlenex commented May 6, 2020

Feedback from 13" MacAir now :)
Tested on Firefox, Safari and Chrome.

@dennisreimann I noticed a few things:

  1. The light-mode background is grey. Our current is white and looks better and easier to read. Any particular reason why you went with gray here?
    Demo docs
    Screenshot 2020-05-06 at 22 44 23

Current docs
Screenshot 2020-05-06 at 22 25 21
2. Payjoin link has no nesting and leads to a broken url
3. I still feel the main content is congested. On 13".theme-default-content:not(.custom) { max-width: 900px; did this which I personally found easier to read (unsure about what others think)
With 900px
Screenshot 2020-05-06 at 22 47 01

Current
Screenshot 2020-05-06 at 22 47 12

  1. We need to add walkthrough.md (I forgot it in the above proposal), unsure where to put it, maybe just add in basics for now

  2. Do you think we should nest all sub-FAQ things, looks a bit too much, doesn't it?

  3. Leaving this as a reminder - don't deploy until we fix development section and determine what goes there

  4. Nesting icons don't exist in the light-mode.

Will post some feedback from a desktop tomorrow though.

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented May 7, 2020

The light-mode background is grey. Our current is white and looks better and easier to read. Any particular reason why you went with gray here?

That's to match the same look we've got in the main app interface, website, directory etc.
Here's what it looks like plain white:

white

  1. Payjoin link has no nesting and leads to a broken url

For me both of that works – can you try a hard refresh circumventing the cache?

  1. I still feel the main content is congested. On 13".theme-default-content:not(.custom) { max-width: 900px; did this which I personally found easier to read (unsure about what others think)

imho 900 is too wide and the lines grow too long, which makes it harder to read. Tried a bit and would not recommend a value bigger than 800.

We need to add walkthrough.md (I forgot it in the above proposal), unsure where to put it, maybe just add in basics for now

Will re-add it to the Basics section with the next commit.

Do you think we should nest all sub-FAQ things, looks a bit too much, doesn't it?

I think the FAQ could get an own main category (like Features or Integrations) so that we move it out of Support and Community.

Nesting icons don't exist in the light-mode.

They are too light, will make them more prominent in both modes.

@pavlenex
Copy link
Contributor Author

@pavlenex pavlenex commented May 7, 2020

I am quite certain some of the issues I pointed out are due to different monitors and color calibrations, that said:

Here's what it looks like plain white:

@dennisreimann Can you check this on your Mac as well? On desktop monitor the gray does not look that weird and width there is good. I am thinking we should slightly adjust the width for 13" but please check the colors on your end. When I look it on a smaller screen, the gray makes it quite distracting to read, though this is a personal taste.

I think the FAQ could get an own main category

The FAQ need to undergo a huge cleanup #504 so I'd keep them as they are now nested, until we figure out the structure there, it's a bit messy rn.

For me both of that works – can you try a hard refresh circumventing the cache?

It leads to https://btcpaydocs.uix.space/FAQ/Payjoin which gives 404, not cache related it seems.

Tested the widths and other things on desktop and double-checked on mobile (to make sure earlier bugs no longer occur) and it all looks good now.

@pavlenex
Copy link
Contributor Author

@pavlenex pavlenex commented May 7, 2020

Just noticed we have two GitHubs, we can use icons for twitter and GH? (I'd leave gh pointing to main repo
github

@Zaxounette
Copy link
Member

@Zaxounette Zaxounette commented May 8, 2020

Pavlenex asked for more eyes for feedback, so here is my tiny contribution =)

Links (broken, misdirects and such)

Menu item changes

Miscellaneous

I have seen no UX/UI or broken by code issues for the time being.

That's all I have for tonight. Got up to the end of the "deployment" menu with this.

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented May 12, 2020

Hey @Zaxounette, thanks for the valuable feedback! The links are fixed, for the "Menu item changes" I'm awaiting @pavlenex' feedback on how to proceed.

@pavlenex
Copy link
Contributor Author

@pavlenex pavlenex commented May 12, 2020

Thanks Dennis for great work and @Zaxounette for in-depth feedback. I really did my best to break stuff around, but imo this thing is very close to being ready for merging.

Our priority right now is to make sure docs are displayed properly and it's critical that no internal links and absolutely critical that no external links are broken. It seems that @dennisreimann has taken care of that.

My questions:

  • Once merged, will the links be properly 301 redirected to a new link @dennisreimann? For example https://btcpaydocs.uix.space/getting-started/connectwallet/ledgerwallet re-directs excellenty, I just want to make sure it's properly handled for search bots as well as humans.
  • I still don't understand why VuePress doesn't allow a hover over a link that's not a page itself. Makes no sense not to have an indicator that Docker Plugins is not clickable. (For example Connect a hardware wallet has it. But then Connect a software wallet doesn't.
    Priority (crucial before we merge)

To Do

Critical

Not a prioriry

Not a priority but would be nice before we merge

  • onClick Image Zoom Effect like we do on old docs

After the merge

Here are just minor annoyances I noticed that are unrelated to Dennis work but once merged we can tackle them, it's good to list things as you test.

  • Docs readme should have a brief intro, point to the front-end and tackle how to contribute together with some styling guides and how to apply them.
  • Re-phrase Please check out our official website , our complete documentation and FAQ for more details.
  • Docker deployment page replaced with automated multi repo readme in btcpayserver-docker.

@Zaxounette
Copy link
Member

@Zaxounette Zaxounette commented May 12, 2020

Before merging, i'll do the same checks I did previously up to "deployment" for the rest of the docs, except maybe the FAQ pages, since i'm working on them (i'll just check for broken links on the FAQ).

I'll work on that tomorrow evening.

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented May 12, 2020

First the bad news: I haven't found a way to do proper 301 redirects on GitHub Pages, yet. From my research this isn't possible on an HTTP level, we can just approach this with a hacked 404 page, but that won't make search engines happy. From what I see we'd havee to add a custom frontend proxy for that.

On a more positive note though:

  • Added image zoom
  • Added hover for the collapsible categories that aren't pages themselves
  • Added aliases for the categories to their first subpage

Also rebased it to match the origin master :)

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented May 13, 2020

As GitHub Pages does not support 301 redirects out of the box, I've generated custom HTML pages that contain a redirect via the <meta http-equiv="refresh"> tag. According to some resources this should be handled equivalently by most search engines.

Firefox and Chrome also report these redirects as 301 in the network inspector, that's what I tried to confirm the desired behaviour. I think this is as far as we can get with GH Pages.

@pavlenex
Copy link
Contributor Author

@pavlenex pavlenex commented May 13, 2020

Yup, was reading on that as well this morning. In my experience if it's 301 in the network inspector it should be enough. I assume we're ready for a PR.

@Zaxounette
Copy link
Member

@Zaxounette Zaxounette commented May 13, 2020

@pavlenex @dennisreimann

Alright ! Second batch of review is in !
Mainly focused on broken links.

Links (broken, misdirects and such)

Menu item changes

Miscellaneous

@pavlenex
Copy link
Contributor Author

@pavlenex pavlenex commented May 14, 2020

Ok, so nothing critical left over as this can all be done after the merge. Ready when you are @dennisreimann.

@dennisreimann
Copy link
Member

@dennisreimann dennisreimann commented May 14, 2020

Done, except for the Menu item changes as I think we should postpone these to upcoming restructurings after the merge.

0.07 Miles-stone automation moved this from To do to Done May 14, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
No open projects
Development

Successfully merging a pull request may close this issue.

5 participants