Multi-site

This app allows to deploy an SPA website, by pointing to distant contents (markdown files) hosted anywhere on github or gitlab.

Why this project ?

( ... so you may ask ... )

We simply didn't want to have all our .md contents in the same repo than the app deploying them into an simili-static website...

Yes, sometimes it's simpler to distinguish the repos you want people to collaborate into, depending if you're expecting them to contribute only to the content texts, or to the code... Usually it's not the same kind of people nor the same required skills.

We also wanted to display some filterable galeries : for instance having a page with a card for every team member, or a card for every project in our portfolio, ... and filtering which cards you want to hide given some tags...

Finally we wanted a reusable app to deploy different websites, without having to fork the project... It's just a matter of changing the .env file and having another contents in another repo...

In short, vuepress or equivalent "static-contents-based" apps weren't versatile nor simple enough for our needs (and we wanted to have a bit of fun doing this project from scratch)...

Who did that ?

( ... Aren't you a bit of a curious fellow ? ... )

This open source tool was developped by the tech cooperative multi (and our website is based on this solution).

Main features

Load distant .md contents hosted on Github or Gitlab ;
Multi lingual (if you provide the dictionnaries) ;
Filters and cards ;
Specific urls for every item you can provide on the fly ;

Setup

The `.env` file

First you have to create an .env file at the root of the project, which can be based on the example.env file :

The template - example.env - is present at the root. You can copy-paste it and customize it wiith your own values.

# from repo root
cp example.env .env

You should have an .env file looking like this :

### - - - - - - - - - - - - - - - - - - - - - ###
### GLOBAL ENV VARS
### - - - - - - - - - - - - - - - - - - - - - ###
# NUXT_ENV_RUN_MODE : dev | preprod | prod
NUXT_ENV_RUN_MODE=dev
NUXT_ENV_HOST=localhost
NUXT_ENV_PORT_DEV=4000
NUXT_ENV_PORT_PROD=4001
NUXT_ENV_APP_TITLE=Multi-site

### - - - - - - - - - - - - - - - - - - - - - ###
### CONTENTS
### - - - - - - - - - - - - - - - - - - - - - ###
NUXT_ENV_SITE_CONFIG=https://github.com/co-demos/multi-site-contents/blob/main/config/global.md

About the distant repo (your `.md` files), the "contents" repo

You can base the organisation of your distant repo by checking the example of this repo.

The distant "contents" repo is organized as follow :

.
├── README.md
├── LICENCE.md
├── config: folder containing the config data necessary to deploy a website with the `multi-site` app
│   ├── global.md : global config file (md and yaml head)
│   ├── navbar.md : config file for navbar butttons and links (md and yaml head)
│   ├── route.md : config file for routes (md and yaml head)
│   └── footer.md : config file for footer links (md and yaml head)
├── images: folder containing images
│   └── <whatever you want> ...
├── texts: folder containing all markdown files, including data files 
    └── <whatever you want> ...

Local development

Then you just have to run the app :

nvm use
npm run dev

... and check if everything seems ok, given the settings from the .env file) :

http://localhost:4000/

Stack

Technologies used for multi-site-app are the followiing :

Nuxt.js - js framework js based on vue.js ;
Buefy - css framework based on Bulma css framework ;
Axios - for http client requests ;
Dotenv - js library to load env variables ;
Gray matter - js library to transform yaml or markdown data into js objects ;
vue-Showdown - js plugin to transform markdown into html ;
highlight.js - to apply css to code blocks (nice colors for every languages) ;

Build Setup

# install dependencies
npm install

# serve with hot reload at localhost:3000
npm run dev

# build for production and launch server
$ npm run build
$ npm run start

# generate static project
$ npm run generate

For detailed explanation on how things work, check out the documentation.

Deployment

These instances are deployed with Netlify :

Test deploy : - rendering these content.
Official website of our tech cooperative multi : - rendering these content
Official Documentation website for the Gitribute project : - rendering these content

Contributions

If you want to propose somme enhancements to our app please make your pull requests against the main branch. We will review that with great pleasure :)

You can also add issues directly in the reop, or add notes or issues from our github "project" page.

Special Directories

You can create the following extra directories, some of which have special behaviors. Only pages is required; you can delete them if you don't want to use their functionality.

`assets`

The assets directory contains your uncompiled assets such as Stylus or Sass files, images, or fonts.