diff --git a/README.md b/README.md index 4b92858..771cad5 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Journal Stack -Welcome to Journal Stack! A documentation stack for scaffolding your doc writing experience! +Welcome to Journal Stack! A documentation stack for scaffolding your doc writing experience with multi-version support! ## Getting Started @@ -27,6 +27,15 @@ A few things I might need help with: - **Testing**: More test use-cases. Currently, they cover the barest minimum and not enough to test anything realistically. Contributions in this regard would very much be appreciated. - **Critical Feedback**: Most important one 😄, critical feedback. Could range from code colocation, to my apprach to fetching and caching, to the documentation itself. I'm open to all feedback. Thank you! +### Contributing Opportunities + +If you are unsure of where to start, here are a few stuffs that would be nice to have: + +- **Improved Typing**: The typing for the app is quite good, however there are a few `any` types sprinkled here and there that could be improved upon. +- **More mock docs**: More docs can't hurt, right? 😄 +- **Improved Documentation**: I don't mean the code itself, I mean this docs you are reading right now. It could be more explanatory, more detailed, more concise, etc. Any improvement would be appreciated. Even typos! +- **Github Actions**: Currently, only github actions regarding syncing the docs to their respective repositories are available. It would be nice to have more actions, such as testing, linting, and expecially deployments. + ## License Journal Stack is licensed under the [MIT License](./LICENSE.md). diff --git a/docs/001-introduction.md b/docs/001-introduction.md index cae016c..029ee42 100644 --- a/docs/001-introduction.md +++ b/docs/001-introduction.md @@ -1,3 +1,14 @@ -# Welcome to Journal Stack 📖! +# Welcome to Journal Stack 📖! (Remix PWA Edition) -## What is Journal Stack? +Journal Stack (Remix PWA) is built with [Remix PWA](https://remix-pwa.run) and is a documentation stack for scaffolding your doc writing experience! + +It includes the following core technologies: + +- [Remix + Vite](https://remix.run) for the web app +- [Fly.io](https://fly.io) for hosting +- [AWS S3 Bucket](https://aws.amazon.com/s3/) for storing documentation content +- [MDX](https://mdxjs.com/) for writing documentation content +- [Tailwind CSS](https://tailwindcss.com/) for styling +- [Playwright](https://playwright.dev/) and [Vitest](https://vitest.dev) for testing + +The following docs would run you through the process of setting up your own documentation stack. \ No newline at end of file diff --git a/docs/002-setting-up.md b/docs/002-setting-up.md index b0959e3..7131702 100644 --- a/docs/002-setting-up.md +++ b/docs/002-setting-up.md @@ -1,2 +1,11 @@ # Setting up your own documentation 🔧 +To set up your own docs, after cloning the repo and installing dependencies, you need to do the following: + +- Rename the `.env.development` file to `.env` and fill in the required environment variables. The AWS part would be discussed in the deployment section, but + for now, fill in the `GITHUB_OWNER` and `GITHUB_REPO` variables with your GitHub username and the name of the repo you want to use for storing your docs content (should be your own forked repo!). +- The `GITHUB_TOKEN` variable is a personal access token that would be used to access your repo. You can generate one via your GitHub settings page. +- Delete the `docs` folder. You wouldn't need it and can refer back to this one if you need to. +- You can also go ahead and delete the `funding.yml` file within `.github` folder, although **DON'T** delete the `workflows` folder within the same folder. + +That's about it! Run `npm run dev` to start the app and you should be good to go! Easy, right? 🚀 \ No newline at end of file diff --git a/docs/003-styling.md b/docs/003-styling.md index 7263b8a..18bf3de 100644 --- a/docs/003-styling.md +++ b/docs/003-styling.md @@ -1,2 +1,15 @@ # Customise the look of your docs 💅 +Extending your styles (or changing it entirely) is pretty easy, the entire docs app is divided into five routes: + +- `_index.tsx`: The index route, this is the landing page of your docs. If you want to abolish a landing page, feel free to uncomment the `redirect` function in the loader. +- `docs.$tag.tsx`: The docs 'tag' route, this is where the heavy lifting happens for versioning. Versioning would be discussed later. It also contains the sidebar wrapper for your app (as you would see, the app is wrapped in a `Sidebar` component that provides quite a lot of information). +- `docs.$tag.$slug.tsx`: The docs 'slug' route, this is where the actual docs content is rendered. +- `docs.$tag._index.tsx`: The docs 'tag index' route, this is where the 'index' route is rendered, if any (this would be explained later in the writing-docs section). +- `updateTheme.tsx`: Handles themes more or less. Journal Stack includes support for system, light and dark themes (Thanks Daniel Kaneem for the concept!) + +That's basically it! There are three main components that make up the docs itself: + +- `app/components/layout/Header.tsx`: The header of the doc, both mobile and desktop-wise. +- `app/components/layout/Sidebar.tsx`: The sidebar of the docs, handles the heavy weighlifting of all the docs manipulation and versioning +- `app/components/layout/Documentation.tsx`: The content of the docs, handles the rendering of the docs content itself. diff --git a/docs/004-writing-docs.md b/docs/004-writing-docs.md index 0e4985f..7d0a1a2 100644 --- a/docs/004-writing-docs.md +++ b/docs/004-writing-docs.md @@ -1 +1,3 @@ -# Write some content ✍️ \ No newline at end of file +# Write some content ✍️ + +Each theme has unique perks and features available within the docs system, this could include unique frontmatter fields, custom components, etc. In this doc, we would be exploring the ones available for Remix PWA theme and how to start writing your own docs.