search

bcc-code / developer.bcc.no

BCC Developer Portal with technical documentation and other resources for developers
https://developer.bcc.no/
5 stars 5 forks source link

Add building instructions #57

Open OmniTroid opened 1 year ago

OmniTroid commented 1 year ago

Currently, there are no instructions on how to build the markdown files into the html pages displayed on the webpage. It's hard to make good change suggestions without being able to build this locally and seeing the change before proposing them.

laurensgroeneveld commented 1 year ago

This is a limitation with the current setup based on https://github.com/bcc-code/bcc-documentation-base. The documentation isn't built from this repository, as VuePress is not a dependency. Rather, we copy the docs folder over to the base repository and build from there.

The benefit is that it's very easy to deploy documentation, as only a GitHub action needs to be added. There is no need to include VuePress and any plugins as a dependency.

The downside is that it's currently impossible to view a local preview from this repository. My workflow in that case has been copy over the files to a local checkout of the documentation-base repository, and run that one locally, and then copy the files back once I'm finished. This works, but isn't a nice user experience. I think this can be partially alleviated with having branch deploy previews as mentioned #67, but that still doesn't enable you to run the website locally.

So perhaps we should have a discussion on changing this setup, as it might limit us too much. We could for example also treat this repository different from the other ones since this one is intended as a full website rather than documentation attached to a repo with other code.

jacobe commented 1 year ago

So perhaps we should have a discussion on changing this setup, as it might limit us too much. We could for example also treat this repository different from the other ones since this one is intended as a full website rather than documentation attached to a repo with other code.

I think this repo is a bit different, yes, since it's also the "root" website of all the other docs sites. Being able to spin it up locally would be great ❤️

laurensgroeneveld commented 1 year ago

I created an issue in the documentation-base repository to discuss on how to solve the current shortcomings: https://github.com/bcc-code/bcc-documentation-base/issues/2