3.9 KiB
| Title | Type |
|---|---|
| Introduction | Document |
import { Prism } from '@astrojs/prism';
Setup Basic Structure
Create a new folder that the entire project will go into and change directory:
<Prism lang="bash" code={mkdir ./project-docs/ cd ./project-docs/}/>
Create the Docker Compose file, docker-compose.yml:
<Prism lang="yaml" code={`
services:
butterflyvu:
image: oci.registry.sudovanilla.org/butterflyvu:latest
restart: always
volumes:
- ./config.json:/app/config.json
- ./docs/home.mdx:/app/src/content/home.mdx
- ./docs/:/app/src/content/docs/
- ./public/:/app/public/
- ./dists/:/app/dist/
nginx: image: nginx:latest restart: always ports: - 4242:80 volumes: - ./dists/:/usr/share/nginx/html/ `}/>
Create the configuration file, config.yml:
<Prism lang="json" code={{ "SiteSettings": { "OrgName": "SudoVanilla", "SiteName": "ButterflyVu", "SiteProtocol": "https", "SiteDomain": "butterflyvu.docs.sudovanilla.org", "SiteBase": "", "MetaColor": "#000", "WhiteLabel": "false", "FooterVersion": "false" }, "FeelbackConfig": { "Enabled": false, "ContentSetId": "0000-0000-0000-0000000", "Present": "like-dislike", "Question": "Did this article help?", "Answer": "Thank you for your feedback." }, "HeaderItems": [ { "text": "Source Code", "link": "https://ark.sudovanilla.org/Korbs/Butterflyvu/" } ], "SidebarItems": [ { "heading": "Introduction" }, { "text": "Introduction", "link": "/introduction/" }, { "heading": "Setup" }, { "text": "Requirements", "link": "/requirements/" }, { "text": "Installation", "link": "/installation/" }, { "heading": "Usage" }, { "text": "Item Link", "link": "/item-link/" }, { "text": "Item Link", "link": "/item-link/" }, { "text": "Item Link", "link": "/item-link/" } ] }}/>
Setup Homepage
You must create, as setup by the Docker Compose file, at ./docs/home.mdx and must be a .mdx file. This is the root of the documentation website.
It should look like this: <Prism lang="jsx" code={`
layout: "@layouts/Splash.astro" Title: "Splash Title" Banner: "./splash.png" PrimaryText: "Get Started" SecondaryText: "Source Code" PrimaryLink: "/introduction/" SecondaryLink: "https://whatever.org"
`}/>
Using the Splash layout is not required, you can change Splash to Document for a regular view, which will also make the sidebar visible on the root page.
Add Documentations
All of your documents should be added to ./docs/ as either .md or .mdx files.
Run
To start ButterflyVu, with Docker, just run:
<Prism lang="bash" code={docker compose up -d}/>
When you start the Docker container, NGINX will startup within it at the set port(usually 4242), then ButterflyVu will begin to build the website to the ./dist/ directory which the NGINX container will point to and host statically.
If NGINX is showing a 403 page, either the website is still being built or something went wrong. Run docker compose logs to see what's happening and debug it, using an unsupported feature in ButterflyVu could cause this or it may simply be a syntax error.
Make sure you're pulling the official Docker image from ONLY the SudoVanilla OCI Registry, which is at oci.registry.sudovanilla.org, anywhere else is not official and anything outside of sudovanilla.org is out of my control. ButterflyVu is distributed as a OCI image, as of v0.1.6, but it shouldn't behave any differently than a regular Docker image.