Flowershow Setup Guide v0.0.1 for Alpha Users (June 2022)

Warning

Please see the new publishing tutorial. This is an old tutorial for alpha users that is now out of date.

Note

🚧 The following steps describe the current, temporary process of using Flowershow (as of June 2022). In the future, many of these tasks will be done by the CLI tool.

Pre-requisites

Node.js installed

Git installed

Currently, there is only one starter template - the default template. The fastest way to use it to bootstrap your website is:

npx create-next-app@latest -e https://github.com/flowershow/flowershow/tree/main/templates/default
# or
yarn create next-app -e https://github.com/flowershow/flowershow/tree/main/templates/default

❕ At the moment, we are in the process of testing Flowershow's core features by using it to create this website's code and content. Thus, for now, Flowershow's GitHub repository is a repository of this website. If you go to the repo, you'll notice it has the following structure:

.
├── templates
│   └── default
│       ├── content -> ../../site/content # symlink to site/content
|      ...
├── site # this website's content and configuration
│   └── content # folder with our md notes and userConfig.js
│       ├── userConfig.js
│       ├── index.md
│       ├── docs
|       ├── demo
│      ...
├── README.md
├── LICENSE
└── .gitignore

/site is where all Flowershow website's data resides. All content that you can read on this website lies inside of the /content subdirectory. To write this content, most of the time we use Obsidian, so if you also use Obsidian, you can imagine /content being your Obsidian vault.

An Important thing to notice here, is that apart from folders with our markdown notes (eg. /demo) there are also two additional files: userConfig.js and index.md.

userConfig.js is where all the user configuration should be written.
index.md, which serves as a front page for our website.

At the moment both of these files are required by Flowershow and should be placed at the root of your notes folder (i.e. inside your Obsidian vault) ¹.

Now, after you've created a Next.js app using Flowershow template, two things that will prevent you from running it: an incorrect content symlink and a missing userConfig.js file. Let's fix this!

Updating symlink to content folder

If you go to the folder where you've next-created your Flowershow app, you'll notice there is a symlink named content, which will point to a non-existing directory ../../site/content - a folder we're using to store this website's markdown. You simply need to update it to point to the directory with your markdown notes (e.g. your Obsidian vault). You can do it with the following commands:

# go to the folder where you've next-created your app
cd my-flowershow-app-folder
# update the incorrect symlink
ln -sfn ~/Path/to/your/md/notes content

To check where the content link points now, you can do:

readlink -f content

Adding userConfig.js file

Now, let's add an empty userConfig.js file to the directory with your notes:

cd ~/Path/to/your/md/notes
touch userConfig.js

At this point, you should be able to run the app. You can check that it compiles by running:

npm run dev
# or
npm run build
npm start

However, when you open the app in your browser, you'll notice the website is welcoming you with 404 page. That's because you don't have an index.md file in the root of your content directory. (All other markdown files will already be available under their corresponding paths.) You can fix this by adding a basic index.md page to the root of your content folder.

cd ~/Path/to/your/md/notes
touch index.md
echo "# Welcome to my Flower Show\!" > index.md

Hurray 🎊! You've just created a website of your markdown notes with a little help from Flowershow 🌷!

Deploying

This part is up to you. Our app is Next.js based, so you can use any of these hosting providers: Vercel, Cloudflare, Netlify, and others to deploy the site.

Sources you may find useful:

In the future, these files will be added automatically by the CLI tool. ↩

Deploying

Footnotes