search

jcalcaben / gatsby-doc-site

A documentation site built on top of Gatsby
MIT License
0 stars 0 forks source link

Convert to doc shell #74

Closed jcalcaben closed 4 years ago

jcalcaben commented 4 years ago

This PR converts the project to a doc shell instead of a doc site project.

Major changes

This PR contains the following significant changes

Content-agnostic shell

The project is now a content-agnostic shell. It can be pointed to a content repository to create the doc site.

Content repository example: https://github.com/jcalcaben/external-markdown-content

Asymmetrical workflows

The workflow for developing locally and for building production are now two different workflows. Local build/preview is done by creating a link to a local project folder outside the project. Production builds pull content data from a specified repository and branch.

Environment variables

Local and production build workflows are configured using environment variables. A .env.example file is included in the project listing the environment variables needed for local and production builds.

Testing

  1. In another directory, clone a content repo, such as https://github.com/jcalcaben/external-markdown-content
  2. Use the .env.local and .env.production files to create a .env file
  3. Set LOCAL_PROJECT_DIRECTORY to the absolute path of the content repo
  4. Set REMOTE_REPOSITORY to the git clone address of the content repo
  5. Set REMOTE_REPOSITORY_BRANCH to a valid remote branch in the content repo
  6. Install yarn dependencies: yarn install
  7. Start the development server: yarn develop
  8. Verify console output saying project is linking to the local project directory:
success open and validate gatsby-configs - 0.053s
success load plugins - 0.783s
Linking local directory: /absolute/path/to/external-markdown-content
success onPreInit - 0.013s
  1. Verify symlink directories data and markdown have been created under the src/external directory
  2. Verify Gatsby builds the site successfully
  3. Edit a file in the remote repository
  4. Verify changes are detected by Gatsby and the page auto reloads
  5. End the dev server with CTRL+C
  6. Start the development server again: yarn develop
  7. Verify console output saying project is already linked:
success open and validate gatsby-configs - 0.051s
success load plugins - 0.556s
Project previously linked. Skipping linking step.
success onPreInit - 0.012s
  1. End the dev server with CTRL+C
  2. Create a production build: yarn build
  3. Verify site builds successfully
  4. Verify the linked directories under src/external have been deleted
  5. Verify the existence of a cached remote repo directory under: .cache/gatsby-source-git/production
  6. Verify the existence of a public directory containing the static site file
  7. Serve the production build: yarn serve
  8. Verify site content is as expected