picklejuice

MkDoc Maker is an AI powered markdown writing assistant that will help write high quality technical documentation faster. You can reference technical thirdparty documents or upload images and let the Ai extract suitable information to add to the document. Or when starting a new documentation project, just write up some messy notes and let the assistant come up with suitable headings. Finally you can also review and tune specific sections of your documentation.

Like with a real in-person writing assistant, you need to give MkDoc Maker information to get started. The more context you can give, the better the output will be. But it isn’t always about getting it to write the final version, more often than not can MkDoc Maker unblock you by providing an idea or a framework to work within. After all, most of us are coders, not documentation writers.

Getting Started

Install Extension

As MkDoc Maker is currently in pre-release alpha you will have been given a .vsix package that can be used to add the extension to your VS Code installation

• Open VS Code and, select Extensions, pick the 3 dots and then select “Install from VSIX…”

• select the provided installer and hit “Install”

Set Email and Password

• Press CTRL + Shift + P to open the command palette and start typing “mkdoc”.
• You will see all available MkDoc Maker commands in the drop down selection
• Select “Enter Email and Password”
• You will be prompted to enter both and a popup will confirm if they have been stored.
• If successful they will be added to your local VS Code Secrets storage

You are now ready to run your first prompt.

Basic Example

• Create a new hello_mkdoc.md file and open it.
• Let’s give it a header “# Welcome to MkDoc Maker” and one subchapter “## Markdown Syntax”
• Add the prompt “//generate” inside your subchapter
• Your file should look like this:

• press the “PLAY” button on the top right of your editor

• MkDoc Maker will take the information it has (not a lot at the moment) and feed this to an AI-model and insert the answer back into the document.
• Buttons will pop up for you to “Accept” or “Reject” the suggestion. Press “Accept”.
• Hit the “preview” button in the top right hand corner to see your Markdown file in all its rendered glory.
• If you accept the generated text, then the extension will automatically change the prompt to “//ignore” so it isn’t accidentally run again.

Refining our Query

Let’s review what we have given the AI as input and what it generated. All we have entered so far is the document title and the chapter title. Not a lot really. The “//generate” command tells it to generate content for this chapter. This allows you to work chapter by chapter and tweak each as you go.

Given that the header for this chapter is “Markdown Syntax”, th AI model returned a summary of how to write markdown. If you are new to markdown, have a read and play with it. Also make sure to toggle the preview on, so you can see how a rendered document looks.

Apart from the standard markdown syntax, on my run, it also combined information from the “MkDocs” project (https://www.mkdocs.org/). Which is a great way to generate static sites based on markdown pages. More on that later. Obviously this is just a “guess” from the AI-model and not correct in this instance.

Let’s say we want to give the AI some more directives and limit the output to 100 lines and put it in a table.

First hit Ctrl + Z until you to your original document and then add a note starting with “// " (note the space!):

# Welcome to MkDoc Maker

## Markdown Syntax

// Limit the output to 100 lines and put in a table.
//generate

Now the output will look something like this:

Providing more Input for the Model

So far we have given the LLM (Large language model) very little information about our project and what we would like it to write about. Given that your project has most likely not been included in the learning data for the model, you can’t use the models “knowledge” for generating your documentation. That said, like with Markdown syntax, you can easily create references to well known technologies if your project uses them.

You can include more information for your prompt through various ways:

• It will always consider the Document and Chapter Titles as well as the rest of the document written so far
• You can add notes as directives
• you can embed images and other resources.

Let’s add this screen shot of VS Code when setting up the Extension and ask it to write a chapter. You may have noticed that MkDoc Maker has automatically created 2 folders next to your markdown document - images and resources. The images folder is used for screengrabs that you want to include in your document, like the ones here in the README.md guide. resources can contain multiple subfolders with images or text files that are useful references to consider when creating the output, but are not shown to the reader of the document.

Images

• save this image to into your images folder:

• The insert a reference to it in your markdown file like this:

  # Welcome to MkDoc Maker
  
  ## Installing the Extension
  
  ![install](images/InstallFromVSIX.png)
  //generate
  
  
  ## Markdown Syntax
  
  // Limit the output to 100 lines and put them in a table.
  //ignore
  

• (note to change the command in the markdown syntax chapter to “//ignore” as we don’t want to run this)

• If you now run the extension, it will analyse the image and consider it in its response.

• You can also add “// notes” to refine the response, or sometimes it is just simple to edit the response until you are happy.

INFO

Large Language Models (LLMs) are amazing at what they do, however under the hood they mostly only predict the next word. They appear to be “intelligent”, however only you as the writer will know your project, so you need to validate the output generated.

In the above example, the AI assumed that the extension is available via the VS Code Extension Marketplace. As we are in Alpha, this is not the case, but how should the AI know? So I deleted this, but it got how to install manually via the .vsix file correctly.

Resources

In addition to images that the user will see as part of the document, we can add more images and also larger text files as references for the AI to consider.

For a VS Code extension, all commands, shortcuts and menu items are defined in a file called package.json. Currently the extension only supports images and text files, so adding a .txt to the end of the file makes it compatible and I can copy it to the resources folder.

I can now include this file using the //use <filename> command:

...

## Commands and Shortcuts

//use package.json.txt
// list all available commands, menue items and shortcuts, don't list internal command names such as mkdocmaker.review
//generate

...

And this is the output:

Awesome - this just saved me a lot of time and with some minor tweaks this is now in this README file.

NOTE

On my first run it would list the internal command references, so I had to tweak the // note to exclude them, hence “…don’t list internal command names such as mkdocmaker.review”. Generally, if you can be specific in your prompts and give examples, it will help the LLM to respond as you would expect. Well, just like a writer, who doesn’t really know what “command names” are, you would give an example to be sure.

Folders

At times you may include multiple files or images as resources. You can add multiple files as comma separated values, however you can also create subfolders and then reference all files in that folder. Often it makes sense to organise your resources in folders as chapters, so you can add resources for each one.

This is an example syntax after moving the file package.json.txt into a folder called commands (note the “/” after the folder name):

...

## Commands and Shortcuts

//use commands/
// list all available commands, menue items and shortcuts, don't list internal command names such as mkdocmaker.review
//generate

...

Supported file formats

We are continually adding more formats that can be used as resources. At the time of writing the following formats are supported:

More Prompts

MkDoc Maker offers a variety of prompts to help you generate different types of content. Here’s a breakdown of the available prompts:

Generating a Summary

Let’s say you want to add an overview or summary to a document. You can use the //sum or //summary prompt. It will use any selected text so you can control what part of the document you want to summaries. If no text is selected it will use the current chapter where the command is located and include all sub-chapters.

Here and example:

Input:

# Welcome to MkDoc Maker

//summary

## Installing the Extension

...

Output:

# Welcome to MkDoc Maker

//ignore

MkDoc Maker is a powerful extension for Visual Studio Code that helps you create high-quality documentation from Markdown files. It provides a range of features to streamline your documentation workflow, including prompts for generating different types of content, a review system for improving your writing, and shortcuts for common tasks. 
 

In this instance, nothing was selected so it will use all sub-chapters which in this case is the whole document as “# Welcome to MkDoc Maker” is the root or top-level chapter.

Reviewing a Section

You can ask MkDoc Maker to make a suggestion to improve a part of text. You can use 2 ways to trigger this feature:

• as with other commands you can use “//review” to review a whole chapter.
• Alternatively you can select a section and right-click to use Review from the context menu.

Here is an example how you could use the review prompt:

ai can review text. will fix typos and have better gramma. also can make examples. Just hightlight and rightclick. mkdoc maker will do the rest.

Will change to:

MkDoc Maker can help you review your text. It can fix typos, improve grammar, and even generate examples. To use this feature, simply highlight the text you want to review and right-click. MkDoc Maker will handle the rest. 

Creating Headings

When starting out on a documentation project, it can be difficult to divide your project into chunks that can serve as headings. The “//headings” or “//head” prompt can help in this situation and generate a structure. It is almost always easier to modify a suggestion rather than write something from scratch.

Here an example:

# MkDoc Maker

//use folders/, commands/, prompts/
//head

As before you can include any resources in your prompt, so if you already have some images or other files, include them to give more context. After a run it will generate a headings structure suggestion:

Generating a testplan (experimental)

The latest edition to MkDoc Maker is a prompt that helps with the creation of test documentation.

In your hello_mkdoc.md document create a new chapter at the end of the document:

## Testing MkDoc Maker

// generate a list of testcases covering all functions and features.
//test

Based on the entire document it will create test case headers.

Workflow and shortcuts

MkDoc Maker is there to help you write documentation faster. Its strength is in automating repeating tasks and integrating AI output directly into your workflow, so you don’t have to switch away from the document you are creating.

VS Code Commands

You can access these commands through the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux) or through the context menu in the editor.

• MkDocMaker: Enter Email and Password: Opens a dialog to enter your email and password for authentication.
• MkDocMaker: Review Selected Text: Sends the selected text to the MkDocMaker review system for feedback.
• MkDocMaker: Generate Chapter: Generates a new chapter based on the header, notes, resources and the remaining current file’s content.
• MkDocMaker: Accept suggestion: Accepts a suggestion provided by the MkDocMaker review system.
• MkDocMaker: Reject suggestion: Rejects a suggestion provided by the MkDocMaker review system.

Menu Items

MkDocMaker also integrates with the editor’s context menu and the “Run” menu in the editor’s title bar.

Editor Context Menu: Available through RIght-click on the text editor

• MkDocMaker: Review Selected Text: Will review the selected text.
• MkDocMaker: Accept suggestion: Accepts the highlighted text suggestion.
• MkDocMaker: Reject suggestion: Rejects the highlighted text suggestion.

Editor Title Bar “Run” Menu:

• MkDocMaker: Generate Chapter: Available when the current file is a Markdown file.
• MkDocMaker: Review Selected Text: Available when the current file is a Markdown file.

Shortcuts

• Ctrl+M, Ctrl+M: Runs the chapter parser and executes commands.
• Ctrl+M, Ctrl+R: Reviews the selected text.
• **Ctrl+M, Ctrl+Y: Accept the text generation. (”Yes")
• Ctrl+M, Ctrl+N: Reject the text generation ("No")