Skip to main content

Installation

Don't worry if this is your first time using any of the tools referenced in this walkthrough - we will guide you through all the steps. If you need help, send us a message on Slack. We're here to help!

IDE or Text Editor#

You will need an IDE (integrated development environment) or text editor to work with Evidence. We like VSCode (Visual Studio Code) because of its layout, integrated console/terminal, and extension library.

VSCode has an extensive documentation site which you can find at this link: https://code.visualstudio.com/docs

Terminal#

The rest of this walkthrough will be done through a terminal. You can either use your own terminal, or open one directly in your IDE.

If you are using VSCode, the shortcut to open a new terminal is

Ctrl + `

System Requirements#

Before installing Evidence, you will need to make sure you have the following installed on your computer:

Node.js (v14 or higher)#

Type the following command into your terminal:

node -v

-v means version.

If you see a version less than 14 or if you don't see a version number returned from that command, you will need to install Node.js - you can install for your operating system here. Choose the "LTS" option (long-term support).

npm (v7 or higher)#

If you downloaded Node.js in the previous step, you will have npm installed (it's included with the Node.js installation).

Run this command to check your npm version:

npm -v

If your npm version number is under 7, you can update npm with the following command:

npm install -g npm@latest

Once you have the right Node.js and npm versions installed, you're ready to create your Evidence project!

Create an Evidence Project#

npx degit is a command to download the code from a github repository. This is going to download our template project and place it into a directory called 'my-project'.

npx degit evidence-dev/template my-project

my-project is the name of the directory that will be created on your computer. You can change this name to whatever you'd like.

After this step, you will have the files you need (they will be in the my-project folder that was created). The next step is to install any required packages or dependencies in those files.

Install Dependencies#

You will need to run an installation on your new directory using the install command in npm. This will identify and download any dependencies from the files in the Evidence package.

For example, Evidence utilizes other npm packages and will require specific versions of those packages - npm handles all of this for you.

The command will work on whichever directory you are in when you run it, so navigate to your new directory:

cd my-project

cd means change directory - we are telling the terminal to go into the my-project directory.

Now that we are in our project, we can run the installation step:

npm install

npm will add all dependencies to the node_modules folder in your project.

Install the VS Code Extension#

The Evidence VS Code extension enables syntax highlighting and basic autocomplete. You can install the extension in 2 ways:

  1. In VS Code, search for "Evidence" in the Extensions menu and click to install

    extension-menu

  2. Install from the the VS Code Marketplace webpage

See VS Code Extension for more information about the extension.

The VS Code extension is not required to build an Evidence project, but it makes the experience of writing your project smoother.

That's it for installation - now you can start your server and use Evidence.

Start the Development Server#

Since you are working with Evidence in development mode, you'll be using a development server which runs on your local computer. This server watches for changes in your markdown documents, and quickly translates them into updated pages in your project.

Use the command below in your terminal to start the dev server:

npm run dev

To stop the dev server, use Ctrl + C

When the dev server is running, you will be able to see your pages in your browser at localhost:3000

Localhost#

If you have not tried web development before, localhost:3000 may look foreign to you. This is your URL for local web development and tells your browser where to send requests. You can think of it in the same way as a normal URL like google.com.

Entering localhost:3000 in your browser tells your browser to send a request to the local server which is using port 3000. If your development server is running, it will receive that request and send back the files needed to display your webpage.

If you navigate to a page in your Evidence project and look at the URL, you will see that each page in Evidence corresponds to a URL (e.g., localhost:3000/examples).

In Review#

We've run the following four commands in our terminal, and we should have a working Evidence site visible in our web browser at localhost:3000.

npx degit evidence-dev/template my-project
cd my-project
npm install
npm run dev

Next Steps#

Now that you're all set up, you can keep working through the getting started guide. The next step is to connect your database.

Help#

If you need help with any of this, reach out to us on Slack.

Help us improve the docs

Please let us know if any of these steps don't work so we can update these docs and help others who will run into the same issues. You can let us know on Slack or by emailing support@evidence.dev.