Quickstart

This section is targetted toward users who are setting their computers up to work with an existing Knowledge Repo installation, and guides a user through their first knowledge post submission. If you are looking to create a new Knowledge Repo repository or server, please refer instead to Deployment.

Submitting your first Knowledge Post

There are several ways to create a Knowledge Post, of which what follows is just one way. For more workflows, refer to: Writing.

Step 1: Install the knowledge_repo tooling

If you have not already done so, follow the installation instructions: Installation.

Step 2: Clone the knowledge repository locally [Git repositories only]

If the repository with which you are going to be contributing is a git repository, clone it locally onto your machine. Note: if you have direct access to a database knowledge repository, this step is not required.

$ git clone <git url> <local path>

Note: If you are just testing the workflow, you can create a test git repository using:

$ knowledge_repo --repo ./test_repo init

Note

If you will be primarily using a single knowledge repository, it is possible to avoid passing it to the knowledge_repo command every time by setting the KNOWLEDGE_REPO environment variable. For example:

export KNOWLEDGE_REPO=<repository uri/path>

For this to be persistent accross sessions, add it to your shell initialization script. If KNOWLEDGE_REPO is set, and points to the knowledge repository with which you would like to interact, you can drop the --repo options in the following.

Step 3: Create a Knowledge Post template

Knowledge Post templates are sample files in their original format which you can use to avoid having to remember how metadata is stored and/or added to the underlying post documents.

For a Jupyter notebook template:

$ knowledge_repo --repo <path/uri_of_repo> create ipynb example_post.ipynb

For an R Markdown template:

$ knowledge_repo --repo <path/uri_of_repo> create Rmd example_post.Rmd

Other templates may be available. You can see all available templates here.

Step 4: Edit the template as normal

Create whatever code cells / plots / LaTeX / etc that you normally would in your work.

Step 5: Add your post to the knowledge repository

$ knowledge_repo --repo <path/uri_of_repo> add example_post.ipynb -p project/example_ipynb
$ knowledge_repo --repo <path/uri_of_repo> add example_post.Rmd -p project/example_rmd

Note that the -p option specifies the path in the repository to which the post should be added.

Step 6: Preview the added post

Sometimes formatting may differ in the Knowledge Web Application compared to that shown in your native environment. Checking that the rendering is what you expect is a good idea before submitting it for peer review.

$ knowledge_repo --repo <path/uri_of_repo> preview <post_path_in_repository>

Step 7: Submit post for review

If everything looks good when previewed, the final step of post submission is submitting your local posts upstream for review, and ultimately, publishing.

$ knowledge_repo --repo <path/uri_of_repo> submit <post_path_in_repository>