b-pmcg / tina-starter-alpaca-mirror

Tina Starter Alpaca

A starting point for your documentation

✨ Features

• Full integration with TinaCMS

• Edit and add new documentation pages

• Fully customizable Navigation

  • Organized your documentation into groups and subgroups
  • Change order of or the navigation

• Theme Customization

  • Colors
  • Fonts
  • Titles

📝 Getting started on localhost

1. Clone the repo git clone https://github.com/tinacms/tina-starter-alpaca.git
2. cd tina-starter-alpaca
3. Set up a GitHub OAuth App
4. Add a new file called .env with the credentials from your Github OAuth App

# OAuth App Credentials from GitHub
GITHUB_CLIENT_ID=************
GITHUB_CLIENT_SECRET=************
SIGNING_KEY=*********

# The path to your repository in GitHub
REPO_FULL_NAME=<GitHub Username>/<Repo Name>

# The base branch that new changes and forks are created from. Defaults to 'master'.
BASE_BRANCH=master

You can learn more about Open Authoring With Github in our guide

5. Install dependencies and run the doc starter:

yarn install
yarn dev

or

npm install
npm run dev

6. Your doc starter should be up and running on http://localhost:3000!

7. If you want the search functionality to work, follow these steps

   1. Make an account at algolia
   2. add environment variables to env file (found it the dashboard under the api keys tab)

    ALGOLIA_APP_ID=***
    ALGOLIA_API_KEY=***
    ALGOLIA_ADMIN_KEY=***
   

   3. run yarn create-indices (this command will have to be run every time you wish to update the indices)
   4. Complete the setup for each index (located on the right side panel)
      1. Configure searchable attributes (must add excerpt)
      2. Configure custom ranking (must add excerpt)
   5. Test and see the search is now working

Deploy on Vercel

Gathering Feedback with Github

People can submit feedback from any documentation page. This feedback is immediately posted to GitHub and stored as issues to the repository of your choosing. GitHub issues are an awesome way to store feeback, make it searchable, filterable on page URL or reaction types for instance, and you can choose to be notified of any new comment on your website 🔔.

Setup

1. Make a personal GitHub access token 👈 This is the GitHub user that posts any new feedback. Feel free to create a dedicated GitHub account for this.
2. Add the following environement variables:

USERNAME_ISSUES=<GitHub username>
GITHUB_ACCESS_TOKEN=<personal access token>
REPO_ISSUES=<repository-name> 

Make sure issues are activated in the repository settings.

3. Run NextJS in development mode to test:

yarn
yarn dev

4. Submit a feedback from the form at the bottom of a documenation page on your site.
5. 👀 Check your GitHub repository if an issue has been created.

Gathering Feedback with another endpoint

If you want to use another service (like Formspree) you can change the endpoint that the form is send to. Simple add the following line to your .env file

FEEDBACK_ENDPOINT=https://example.com

🔗 Hosting

• See how to deploy NextJS on Vercel.
• You have to create a GitHub OAuth App with your Vercel URL.

Issues

If you notice any bugs or have any problems please report them here