Docs/ButterflyVu
Docs/ButterflyVu
1
Fork 0
Code Issues Pull requests Activity

🚀 Init

Browse source
This commit is contained in:
Korbs 2024-12-12 20:59:43 -05:00
commit 6154454011
7 changed files with 275 additions and 0 deletions

1
.gitignore vendored Normal file
View file

@ -0,0 +1 @@
dists

45
config.json Normal file
View file

@ -0,0 +1,45 @@
{
"SiteSettings": {
"OrgName": "SudoVanilla",
"SiteName": "ButterflyVu",
"SiteProtocol": "https",
"SiteDomain": "butterflyvu.docs.sudovanilla.org",
"SiteBase": "",
"MetaColor": "#000",
"WhiteLabel": "false",
"FooterVersion": "false"
},
"FeelbackConfig": {
"Enabled": false,
"ContentSetId": "566e8b96-c65e-4bf7-87df-d22a9f4994a2",
"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/"
}
]
}

23
docker-compose.yml Normal file
View file

@ -0,0 +1,23 @@
services:
butterflyvu:
image: oci.registry.sudovanilla.org/butterflyvu:latest
restart: always
volumes:
# Configuration
- ./config.json:/app/config.json
# Homepage
- ./docs/home.mdx:/app/src/content/home.mdx
# Your Documentations
- ./docs/:/app/src/content/docs/
# Use this add images locally and update your favicon
- ./public/:/app/public/
# Generated, do not touch
- ./dists/:/app/dist/
nginx:
image: nginx:latest
restart: always
ports:
- 4242:80
volumes:
- ./dists/:/usr/share/nginx/html/

9
docs/home.mdx Normal file
View file

@ -0,0 +1,9 @@
---
layout: "@layouts/Splash.astro"
Title: "ButterflyVu Documentation"
Banner: "https://md.sudovanilla.org/images/logos/butterflyvu/ButterflyVu%20-%20Original.png"
PrimaryText: "Get Started"
SecondaryText: "Source Code"
PrimaryLink: "/introduction/"
SecondaryLink: "https://ark.sudovanilla.org/Korbs/ButterflyVu"
---

137
docs/installation.mdx Normal file
View file

@ -0,0 +1,137 @@
---
Title: Introduction
Type: 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.

21
docs/introduction.mdx Normal file
View file

@ -0,0 +1,21 @@
---
Title: Introduction
Type: Document
---
## What is it?
ButterflyVu is a documentation website for your projects and company, built on Astro, compatible with Zorn. Easy to use and setup with any container-based tools such as Docker and Podman.
## Showcase
ButterflyVu is an in-house project, so most SudoVanilla projects are already using ButterflyVu for their documentations.
- [Zorn Player](https://zorn.docs.sudovanilla.org)
- [Devojo](https://devojo.docs.sudovanilla.org)
## Support
If you're having issues with ButterflyVu, feel free to submit an issue to the repository on [SudoVanilla Ark](https://ark.sudovanilla.org/MinPluto/Zorn/).
If you're unable to create an issue on either sites, for whatever reason, [email support](mailto:support-PLEASE-REMOVE-THIS-FOR-SPAM-PROTECTION@sudovanilla.org) is available.

39
docs/requirements.mdx Normal file
View file

@ -0,0 +1,39 @@
---
Title: Requirements
Type: Document
---
import { Prism } from '@astrojs/prism';
## With Astro
If you're wanting to contribute to ButterflyVu and make changes yourself to the project itself, you'll need to have tools installed that work with building Astro websites.
SudoVanilla recommends that you have at least Bun installed. With this, NodeJS is NOT required at all, Bun can work alone. SudoVanilla highly recommends using the Bun package manager for all Astro projects, if you need to implement i18n into your Astro website then you'll need NodeJS at that point.
Install Bun with their bash script:
<Prism lang="bash" code={`
curl -fsSL https://bun.sh/install | bash
`}/>
For Windows, I using the WSL with either Alpine or Debian, your choice. Or run `powershell -c "irm bun.sh/install.ps1 | iex"`.
## With Docker
### Production
It is expected for the server admin to use the Docker method for production use, as it is recommended, so please install the Docker Engine.
- [Install Docker Engine for Windows](https://nickjanetakis.com/blog/install-docker-in-wsl-2-without-docker-desktop) (WSL Method)
- [Install Docker Engine for macOS](https://formulae.brew.sh/formula/docker) (Homebrew Method)
- [Install Docker Engine for Linux](https://docs.docker.com/engine/install/#supported-platforms)
SudoVanilla does NOT recommend using the Docker Desktop application, as it is proprietary software.
That's it.
### Development
If you're planning on building your own Docker image, SudoVanilla uses `buildah`.
You'll need Buildah to continue. Just run `bun run docker:build`.