One of the prevailing thoughts of deployable software is to vendor everything, i.e. have everything needed included with the application and pull in basically nothing. We already vendor most of the JS we need (need to still vendor Bootstrap but that's a different issue) and the question occurred to me as to whether we should include the compiled output of retype in the docs folder and use something like srcdocs for the markdown source BECAUSE retype is a node js / dotnet application and we can't vendor that.
The idea then would be to add a route in nginx so that the compiled documentation is always available, i.e. example.com/docs/..., but only if the deploying party decides to add the docs route (something that can be added into the documentation).
Downsides:
compiled folder of HTML that's only useful in limited circumstances
more to clone
more changes to potentially clog up PRs
we already host the docs on the website and that's working fine
Advantages:
fully compiled documentation is always accessible in the codebase even if offline
does not require retype being installed for any downstream user of Alexandria unless they want to update the docs
can be deployed as part of any install by adding one optional route to nginx, allowing each instance to host their own documentation for their specific version
One of the prevailing thoughts of deployable software is to vendor everything, i.e. have everything needed included with the application and pull in basically nothing. We already vendor most of the JS we need (need to still vendor Bootstrap but that's a different issue) and the question occurred to me as to whether we should include the compiled output of
retype
in the docs folder and use something likesrcdocs
for the markdown source BECAUSEretype
is a node js / dotnet application and we can't vendor that.The idea then would be to add a route in nginx so that the compiled documentation is always available, i.e.
example.com/docs/...
, but only if the deploying party decides to add the docs route (something that can be added into the documentation).Downsides:
Advantages:
retype
being installed for any downstream user of Alexandria unless they want to update the docs