diff --git a/Dockerfile b/Dockerfile index 6161426..8394427 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,17 +1,6 @@ -# Use Python 3.10.11 image as the base -FROM python:3.10-slim-bullseye - -# Set the working directory +FROM python:3.10-alpine WORKDIR /app - -# Copy the current directory to the container COPY . /app - -# Install dependencies RUN pip install --no-cache-dir -r requirements.txt - -# Expose port 8000 EXPOSE 8000 - -# Start mkdocs dev server CMD ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"] \ No newline at end of file diff --git a/README.md b/README.md index 8e8862a..54a3589 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # HackforLA.org Wiki -This repository houses the documentation for the Hack for LA website team. The live site is available at [https://hackforla.github.io/website-wiki/](https://hackforla.github.io/website-wiki/). The documentation is built using [MkDocs](https://www.mkdocs.org/) and is styled with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. +This repository houses the documentation for Hack for LA's website team. The documentation is built using [MkDocs](https://www.mkdocs.org/) and is styled with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme. -**Note**: Issues related to this wiki are tracked in the [hackforla/website repository](https://github.com/hackforla/website). For more information on the current state of the wiki, please refer to the [How to Contribute to the Wiki](https://github.com/hackforla/website/wiki/How-to-Contribute-to-the-Wiki) page. +**Note**: Issues related to this wiki are tracked in the [hackforla/website repository](https://github.com/hackforla/website). + +For more information on the current state of the wiki, please refer to the [How to Contribute to the Wiki](https://github.com/hackforla/website/wiki/How-to-Contribute-to-the-Wiki) page. --- @@ -10,10 +12,11 @@ This repository houses the documentation for the Hack for LA website team. The l ### Clone or Fork the Repository -Clone your fork or the original repository locally: - ```bash git clone https://github.com/YOUR_USERNAME/website-wiki.git +``` + +```bash cd website-wiki ``` @@ -21,46 +24,75 @@ cd website-wiki ### With Docker -1. **Pull the Docker Image**: To ensure you have the latest Docker image, run: +The easiest way to get your local mkdocs server running and see your changes in real-time is by using Docker Compose. + +1. **Start the mkdocs Server** + + To serve your site locally, run: ```bash - docker pull vraer/hfla-website-wiki:latest + docker-compose up ``` - -2. **Start the Development Server**: To start the development server, run: + + This launches the mkdocs server, which serves your documentation site and listens for changes. Your site will automatically update as you make changes to the documentation. + + If you prefer to run the server in the background, use: ```bash - docker run --rm -it -p 8000:8000 -v ${PWD}:/docs vraer/hfla-website-wiki:latest + docker-compose up -d ``` -Your site will now be accessible at . +2. **View Your Site** -#### Building the Documentation + Open a web browser and go to `http://localhost:8000` to see your mkdocs site live. -To build the documentation into a `site` folder, run: +3. **Stop the Server** + + To stop the server, if running in the foreground, press `Ctrl+C` in your terminal. For detached mode, use: + + ```bash + docker-compose down + ``` -```bash -docker run --rm -it -v ${PWD}:/docs vraer/hfla-website-wiki:latest build -``` ### With Python virtualenv +**Note for Windows Users Installing Python:** + +During the Python installation process, make sure to select the option **"Add Python 3.x to PATH"**. This step will allow you to run Python and pip commands from the Command Prompt. + 1. **Create a Virtual Environment**: - ```python + For macOS/Linux: + + ```bash python3 -m venv venv ``` + For Windows: + + ```cmd + python -m venv venv + ``` + 2. **Activate the Virtual Environment**: + For macOS/Linux: + ```bash source venv/bin/activate ``` + For Windows: + + ```cmd + .\venv\Scripts\activate + ``` + 3. **Install Required Packages**: ```bash - pip install -r requirements.txt + pip install -r requirements.txt ``` 4. **Start the Development Server**: @@ -69,11 +101,14 @@ docker run --rm -it -v ${PWD}:/docs vraer/hfla-website-wiki:latest build mkdocs serve ``` + Your site will now be accessible at . + 5. **Build the Documentation**: + Building the mkdocs site generates static HTML files. This step is typically reserved for testing custom hooks or preparing the documentation for deployment. + ```bash mkdocs build ``` -Your site will now be accessible at . - + This compiles your Markdown files into static HTML files, placing them in the `site` directory. diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..a1aa056 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,9 @@ +version: '3.8' +services: + mkdocs: + build: . + ports: + - "8000:8000" + volumes: + - .:/app + command: mkdocs serve --dev-addr=0.0.0.0:8000 diff --git a/mkdocs.yml b/mkdocs.yml index 2b6e673..c99b536 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -68,7 +68,7 @@ plugins: minify_html: true - search: {} - autolinks: {} - - git-revision-date-localized: {} + # - git-revision-date-localized: {} markdown_extensions: - abbr @@ -80,7 +80,8 @@ markdown_extensions: - toc: title: On this page permalink: "#" - - pymdownx.betterem + - pymdownx.betterem: + smart_enable: all - pymdownx.caret - pymdownx.details - pymdownx.emoji: @@ -90,8 +91,7 @@ markdown_extensions: - pymdownx.inlinehilite - pymdownx.keys - pymdownx.magiclink: - hide_protocol: false - normalize_issue_symbols: false + normalize_issue_symbols: true user: hackforla provider: github repo: website diff --git a/requirements.txt b/requirements.txt index 5ee0cfe..5bce777 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,7 +4,6 @@ markdown>=3.2 mkdocs>=1.5.0 mkdocs-autolinks-plugin==0.7.1 mkdocs-awesome-pages-plugin -mkdocs-git-revision-date-localized-plugin==1.2.0 mkdocs-material>=9.0.0,<10.0.0 mkdocs-material-extensions>=1.1 mkdocs-minify-plugin