How to write Docs in Obsidian and Publish them with NextJS.

Introduction to smooth and proffesional process

What the process looks like? It's simple:

1. Write in Obsidian & push (pushing can be automated too.
2. Get a cup of tea.
3. Come back and see the updated changes on your production site.

Ok. So how does it work?

We trigger pre and postbuild hooks that update NextJS project with Obsidian-written docs.

1. Repo structure possibilities
2. Initiating Obsidian vault
3. Prepare prebuild hook

1. Repo structure possibilities

Depending on the goal and size of your docs, you can have 2 choices where to settle the Obsidian vault.

1. One would be to havr a big repo and documentation that you don´t want to publish in it's entireity. Then part of the documentation could be called /main_repo/docs/Tutorials or /main_repo/docs/technical-documentation. Remember that the goal of this chapter is to show how to publish the changes made with obsidian in a private or public repo to your production site visible by the whole internet. This example would use prebuild step to copy this folder content to front-end repo.

2. The point here is to open the Obsidian vault in a location where you have your NextJS documentation folder. This way you will be writing your documentation directly in the NextJS repo e.g. /main_repo/frontend/src/pages/docs/main-tutorial-page.md. The downside of this approach is that when writing documentation it is good to have some attachments, other files etc, that could land by mistake in your pages folder and NextJS would repack them to be publicly available or creash build process if the files are not supported by webpack.

I personally chose the first option and this option will be discussed here.

2. Initiating Obsidian vault

You can start creating docs in an exisitng repo or prepare beforehand. In the real world it's more probably that the docs are result of something that you have already made so feel free to crete docs folder in your repo root (also consider learning about documentation driven development).

Obsidian vault is a name for opening local folder and using it in Obsidian program. The vault name is there to remind you that Obsidian can have a sligltly different formatting or needs (e.g. using tags). Remember that if you had some docs created already, there might be problem with downloading your vault to Obsidian - if that happens make sure about custom formatting that comes with obsidian. You can adjust it in the program's settings. You can always use obsidian plugins that help with formatting (if yours was not quite markdown/obsidian aligned)

You can treat this whole process as an Obsidian md files publish alternative. The main way would be to use Obsidian paid tier. This does not fit into our goal where the docs are located in a specific URL and can be build and queried by Google robots entering the site we are documenting. This is an alternative that uses official Obsidian way of creating docs - not completly other software.

3. Prepare prebuild hook

In your package.json file has scripts. Usually you run npm run dev or npm run test, sometimes build. What is less common to know is that when you run npm run build npm will execute prebuild script before and after it.

We need one pre script and it looks like that:

// package.json file

//...
"scripts": {
    "dev": "next dev",
    "prebuild": "node ./src/scripts/UpdateAppTutorials.js",
    "build": "next build",
//...

You can see that now we need a file caleed UpdateAppTutorials.js and it's need to be located in the root frontend folder with our nextjs project. Continuing the example from the point 1 it will now look like this: /main_repo/frontend/src/scripts/UpdateAppTutorials.js.

That script will be responsible for copying the files from /main_repo/docs/ to /main_repo/frontend/src/pages/docs/

The script should contain some node js code that will do the job:

// UpdateAppTutorials.js
// All documentation is written in docs folder in root of the repo.
// Content of docs/tutorials is visible on the page after build
// This script runs on prebuild and updates changes made to docs so they are ready for build

const fse = require('fs-extra')
const path = require('path');

const DOCS_MAIN = path.join(process.cwd(), '../docs/tutorials')
const DOCS_NEXTJS = path.join(process.cwd(), '/src/pages/docs')

try {
  fse.copySync(DOCS_MAIN, DOCS_NEXTJS, { overwrite: true })
  console.log('Copied files from main docs repo folder!')
} catch (err) {
  console.error(err)
}

Don't forget to install fse & path.

Perfect.

What now? Now you need to have logic within your NextJS project that deals with markdown files and turns them into pages.

If you do not have that part and want to know, drop me a msg to let me know if there is a need for such a tutorial.