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

Build docs with Vuepress #26

Merged
merged 7 commits into from Jul 29, 2019

Conversation

@dennisreimann
Copy link
Collaborator

commented Jul 25, 2019

This is an alternative build approach than what was layed out in #2.

I talked to @MaxHillebrand and @thunderBiscuit about the advantages VuePress has over GitBook, namely:

  • it lets you build the project locally and see changes immediately
  • it is more flexible in terms of adapting the layout
  • the resulting site is more performant and usable offline
  • it is open source, whereas GitBook takes the commercial route nowadays

I have set up VuePress on this branch and would incorporate your feedback.
The project README now also contains the setup instructions you need to run the docs locally.

Prerequisite: Node.js needs to be installed.

dennisreimann added some commits Jul 25, 2019

Basic VuePress setup
Signed-off-by: Dennis Reimann <mail@dennisreimann.de>
Structure pages for VuePress
Signed-off-by: Dennis Reimann <mail@dennisreimann.de>
Fix build instructions
Signed-off-by: Dennis Reimann <mail@dennisreimann.de>
@dennisreimann

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 26, 2019

We got this set up for @MaxHillebrand and he will be testing this. In case we can decide on using this setup, I could go ahead do some of the layout adjustments and take care of the deployment.

@MaxHillebrand

This comment has been minimized.

Copy link
Collaborator

commented Jul 26, 2019

Thanks @dennisreimann!!

I have a local instance up and running, I really like that it can be build locally.
It looks very nice visually already, and it seems that there are many ways to customize it further.

I'll play around with it some more, but because of the reasons described above, at first glance I think that VuePress > GitBook.

@MaxHillebrand

This comment has been minimized.

Copy link
Collaborator

commented Jul 26, 2019

Haha - what I like most about it so far, is that my dark-mode firefox plug-in work with it - because it does not for GitBook 😆

Same question as in #14, how should we best add the images? A local /img/ directory, or work with imgur as in the main repo?

@dennisreimann

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 26, 2019

how should we best add the images?

You can put them into docs/.vuepress/public/, that's where I have placed the logos already.

Referencing them then can be done by using /image.png (or /folder/image.png in case you want to structure them further in the public dir).

@dennisreimann

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 26, 2019

Regarding the navigation structure in the topbar and sidebar: Some of the thinsg that cannot be configured via the file structure are set in docs/.vuepress/config.js – the detailed docs for that are in the VuePress default theme config.

@MaxHillebrand

This comment has been minimized.

Copy link
Collaborator

commented Jul 26, 2019

The dennisreimann:vuepress branch is build live here.

Ready for review!

@MaxHillebrand

This comment has been minimized.

Copy link
Collaborator

commented Jul 26, 2019

Can you please remove the docs/SUMMARY.md file, this is only used by GitBook.

@mayankchhabra

This comment has been minimized.

Copy link

commented Jul 26, 2019

+1 for local builds, will be much more efficient to preview when styling, theming and structuring vs GitBook.

@thunderBiscuit

This comment has been minimized.

Copy link
Contributor

commented Jul 26, 2019

ACK.

dennisreimann added some commits Jul 26, 2019

Remove gitbook summary file
Signed-off-by: Dennis Reimann <mail@dennisreimann.de>
Prepare deployment
Signed-off-by: Dennis Reimann <mail@dennisreimann.de>
@dennisreimann

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 26, 2019

I also added the deployment scripts – we can hook all of that up and deploy to the actual domain once we decided where this should go.

@thunderBiscuit

This comment has been minimized.

Copy link
Contributor

commented Jul 26, 2019

Once this is merged we can start working on the structure. Mostly the config.js file needs a bit of love in order to create the sidebars that will make the site more useable.

@MaxHillebrand

This comment has been minimized.

Copy link
Collaborator

commented Jul 27, 2019

Fantastic work peers!!

Thanks for preparing the deployment @dennisreimann!
You're right @thunderBiscuit, the structure needs to be fine tuned, and that should happen sooner rather than later. I think we should continue the discussion on slack to condense a couple ideas, then open a new issue with a detailed proposal, and then present it at mondays dev-call to get feedback.

@MaxHillebrand

This comment has been minimized.

Copy link
Collaborator

commented Jul 27, 2019

Ok, we can compare the two now!!

GitBook and VuePress

@thunderBiscuit

This comment has been minimized.

Copy link
Contributor

commented Jul 27, 2019

I suggest merging this on a special vuepress branch. The deploy.sh script will force push to a new branch called gh-pages, which we then set the repo to track and deploy as gitpages. The two implementations (GitBook and VuePress) can easily coexist for now, at least for the time it will take for us to pick a winner.

@MaxHillebrand

This comment has been minimized.

Copy link
Collaborator

commented Jul 27, 2019

Mhhh, but this PR does delete the GitBook stuff...
idk, but I think it is better to wait the two more days till the dev-call where we will make the decision between GitBook [close PR] and VuePress [merge PR].

But you can commit directly to the dennisreimann:vuepress branch.

@MaxHillebrand

This comment has been minimized.

Copy link
Collaborator

commented Jul 28, 2019

I resolved some conflicts of the change to consistent "CoinJoin" spelling in #28.
I think this branch is clean now - but I might have messed up with the vuepress header of the /docs/README.md - can someone please review this?

Apply custom CNAME
Signed-off-by: Dennis Reimann <mail@dennisreimann.de>
@thunderBiscuit

This comment has been minimized.

Copy link
Contributor

commented Jul 28, 2019

@MaxHillebrand The docs/README.md is now being used for the landing page instead of the first page of the documentation per se (which is now GettingStarted.md). By adding to the readme file, we are simply creating a super long landing page. I assume that might not have been your intention.

@MaxHillebrand

This comment has been minimized.

Copy link
Collaborator

commented Jul 29, 2019

Yes, we should structure the repo so that it fits VuePress, it makes of course sense to have the README.md now be the landing page - which looks really really cool, and I think we can do a lot with this.
The GettingStarted.md file looks good :)

@MaxHillebrand MaxHillebrand merged commit 7a05c3c into zkSNACKs:master Jul 29, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.