docs/
directory.Breadcrumbs
Table of Contents
docs/lang/en.json
, you are free to change the text:
menu
property without having to rebuild the html files. The menu
property is an array of objects in format of {name: "Link name", href: "/link-url"}
breadcrumbRoot
property without having to rebuild the html files. The change here will appear on the Breadcrumbs
component. If you remove this property, no root will be included.sidebars
property without having to rebuild the html files. These sidebars
determine are for setting custom Table of Contents per document instead of the automatically generated one. Configure the sidebars
property with a key that is the value of location.pathname or the base path of the .md within docs
. Each pathname is an object with keys items
(array of objects) and isCascading
(boolean). Setting isCascading to true means that any subsequent docs within the pathname subdirectories will also have the same Table of Contents./src/
- Any source code used to generate the hosted documents (not directly published)/docs/
- Contains the markdown files that are hosted as html by GitHub Pages./docker/
- The files to create a docker image which can be run locally to test the site. This image is built and available from DockerHub as hubmap/github-pages-server
This repository relies on the data_submission_guide as a submodule to function. The
file .gitmodules
contains the configuration for the URL and specific branch of the submodule that is to be used. Once
you already have cloned this repository and switched to the target branch, to load the latest data_submission_guide
submodule:
git submodule update --init --remote
Only need to set this up if there is a need to add new functionality, features, styles to the templates. To view /docs
as they'd appear on GitHub pages, see mimicking GitHub pages.
cd documentation
npm i .
npm start
Open http://localhost:3005 with your browser to see the result.
Note: This is only for viewing the styles, layouts and JS functionality generated through /src
changes, ideally should set up the docker server for mimicking of GitHub pages to test fully.
See Below: Mimicking GitHub Pages Locally
npm run css # builds CSS files to `/docs/css/main.css` and copies to `./docs/_site` GitHub build folder
npm run js # builds Js files to `/docs/js/main.js` and copies to `./docs/_site` GitHub build folder
npm run html # builds the PUG layout and pages to `/docs[/_layouts]`
npm run build # builds all of the above
Serve docs
folder locally.
Should have serve
module installed after running npm i .
Note: This is only for viewing the styles, layouts and JS functionality generated through /src
changes, ideally should set up the docker server for mimicking of GitHub pages to test fully.
See Below: Mimicking GitHub Pages Locally
serve ./docs
docs
:
foo-who/
, incorrect: foo_who/
./package.json
The docker image built out of the /docker
directory provides a local server to mimic the GitHub Pages server. This image has been built and pushed to DockerHub.
To run it you must mount a local copy of the /documentation/
repo as a volume in the container as the volume /software-docs/
and expose port 4000
locally.
The runlocal.sh
script is provided to help with this. You must have docker installed and running.
To test this repository locally using the docker image execute the runlocal.sh
script included in this directory like:
sh ./runlocal.sh /full/absolute/path/to/the/downloaded/repository
When the container is running correctly you'll be able to navigate to https://localhost:4000/ in a local browser.