diff --git a/docs/README.md b/docs/README.md index 7277b48..29f5a80 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ This directory contains the documentation for the `base` project. - **[Docker-based Development Environment](./docker.md)**: Instructions on how to use the included Docker setup for a consistent development environment. - **[GitHub Codespaces](./github-codespaces.md)**: A guide to using GitHub Codespaces for a cloud-based development experience. - **[GitHub Pages Site](./github-pages.md)**: Information on how the project's documentation is automatically built and deployed as a website. +- **[Use Case: A Publishing Platform](./use-case-publishing.md)**: A detailed guide on using this repository as a platform to create and publish your own website. - **[GitHub Workflows](./github-workflows.md)**: An explanation of the CI/CD workflows for linting, testing, and releasing. - **[Licensing Information](./licensing.md)**: Details on the MIT License and how to properly attribute copyright. - **[Deploying to Render.com](./render.md)**: Instructions for deploying the project to the Render.com platform. diff --git a/docs/base.md b/docs/base.md index c8b2c43..bffcf8a 100644 --- a/docs/base.md +++ b/docs/base.md @@ -8,7 +8,7 @@ The development of this template is guided by a few core principles: 1. **Code-Independent:** The template should not be tied to a specific programming language. The goal is to provide a solid foundation of repository structure, CI/CD, and best practices that can be adapted to any language or framework. -2. **Well-Documented:** Every component, workflow, and configuration file is documented in the `docs` directory. The goal is to make the repository easy to understand and modify. +2. **Well-Documented:** Every component, workflow, and configuration file is documented in the [`docs`](./) directory. The goal is to make the repository easy to understand and modify. 3. **Guidance Over Prescription:** The template provides sensible defaults and placeholder files that guide the user on how to create their own project-specific content, such as contributing guidelines or a license. diff --git a/docs/github-pages.md b/docs/github-pages.md index b88adf3..dce15c4 100644 --- a/docs/github-pages.md +++ b/docs/github-pages.md @@ -10,18 +10,18 @@ Before the workflow can deploy your site, you must configure your repository to 2. **Select Pages:** In the left-hand sidebar, click on **Pages**. 3. **Set the Deployment Source:** Under the "Build and deployment" section, you will see a **Source** option. Select **"GitHub Actions"** from the dropdown menu. -After you select "GitHub Actions", the UI may present you with suggestions for common workflows (e.g., "GitHub Pages Jekyll", "Static HTML"). **You can ignore these suggestions.** This repository already contains a custom, pre-configured workflow (`.github/workflows/pages.yml`) that will be used automatically. +After you select "GitHub Actions", the UI may present you with suggestions for common workflows (e.g., "GitHub Pages Jekyll", "Static HTML"). **You can ignore these suggestions.** This repository already contains a custom, pre-configured workflow ([`.github/workflows/pages.yml`](../.github/workflows/pages.yml)) that will be used automatically. -> **Note:** If you do not perform this setup step, the `pages.yml` workflow will fail with a "Get Pages site failed" or "HttpError: Not Found" error. +> **Note:** If you do not perform this setup step, the [`pages.yml`](../.github/workflows/pages.yml) workflow will fail with a "Get Pages site failed" or "HttpError: Not Found" error. ## How It Works -The site is built and deployed by the `.github/workflows/pages.yml` workflow. Here's a summary of the process: +The site is built and deployed by the [`.github/workflows/pages.yml`](../.github/workflows/pages.yml) workflow. Here's a summary of the process: 1. **Trigger:** The workflow runs automatically on every push to the `main` branch. 2. **Jekyll Build:** It uses the standard `jekyll-build-pages` GitHub Action to build a static website. -3. **Homepage:** It is configured to use the root `README.md` file as the content for the homepage (`index.html`) of the site. -4. **Styling:** The `_config.yml` file in the root of the repository specifies the `jekyll-theme-primer` theme, which gives the site the standard GitHub look and feel. +3. **Homepage:** It is configured to use the root [`README.md`](../README.md) file as the content for the homepage (`index.html`) of the site. +4. **Styling:** The [`_config.yml`](../_config.yml) file in the root of the repository specifies the `jekyll-theme-primer` theme, which gives the site the standard GitHub look and feel. 5. **Deployment:** The built static site is then deployed to GitHub Pages. ## Accessing the Site diff --git a/docs/licensing.md b/docs/licensing.md index d59cf72..f847de4 100644 --- a/docs/licensing.md +++ b/docs/licensing.md @@ -1,6 +1,6 @@ # Licensing Information -This repository is distributed under the MIT License, the full text of which is available in the `LICENSE` file. +This repository is distributed under the MIT License, the full text of which is available in the [`LICENSE`](../LICENSE) file. ## What is the MIT License? @@ -10,7 +10,7 @@ The MIT License is a permissive free software license originating at the Massach ## How to Use the `LICENSE` File -The included `LICENSE` file contains a copyright line for the `base` template itself: +The included [`LICENSE`](../LICENSE) file contains a copyright line for the `base` template itself: `Copyright (c) 2025 Attogram Project` diff --git a/docs/prettier.md b/docs/prettier.md index 3330e65..7012958 100644 --- a/docs/prettier.md +++ b/docs/prettier.md @@ -32,11 +32,7 @@ pnpm add --save-dev --save-exact prettier bun add --dev --exact prettier ``` -After installing Prettier, you should create a configuration file to let editors and other tools know that you are using Prettier. - -```bash -echo {} > .prettierrc -``` +This repository includes a default configuration file, [`.prettierrc`](../.prettierrc), so you don't need to create one from scratch. It lets editors and other tools know that you are using Prettier. It is also useful to create a `.prettierignore` file to specify which files should not be formatted by Prettier. diff --git a/docs/template-repo.md b/docs/template-repo.md index 2048a0c..e7ac34f 100644 --- a/docs/template-repo.md +++ b/docs/template-repo.md @@ -15,14 +15,14 @@ This allows users to generate new repositories from this one. When adding or modifying files, remember that they will be copied verbatim into new repositories. - **Use Placeholders:** For project-specific information like copyright notices or contact information, use clear placeholders like `[year] [fullname]` or `[INSERT CONTACT METHOD]`. -- **Write Instructional Content:** Files like `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` should not be prescriptive. Instead, they should guide the end-user on how to create their own versions of these files. +- **Write Instructional Content:** Files like [`CONTRIBUTING.md`](../CONTRIBUTING.md) and [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) should not be prescriptive. Instead, they should guide the end-user on how to create their own versions of these files. - **Relative Links:** Use relative links for all in-repository links (e.g., `[link text](./path/to/file.md)`) to ensure they work correctly in the generated repositories. ## Maintainer Checklist Before tagging a new release of `base`, review the following: -- [ ] All documentation in the `docs/` directory is up-to-date with the latest changes. -- [ ] All workflows in `.github/workflows/` are tested and functioning. +- [ ] All documentation in the [`docs/`](./) directory is up-to-date with the latest changes. +- [ ] All workflows in [`.github/workflows/`](../.github/workflows/) are tested and functioning. - [ ] All placeholder files are clear and provide good guidance. -- [ ] The `AGENTS.md` file has been updated to reflect any changes that would affect AI assistants. +- [ ] The [`AGENTS.md`](../AGENTS.md) file has been updated to reflect any changes that would affect AI assistants. diff --git a/docs/use-case-publishing.md b/docs/use-case-publishing.md new file mode 100644 index 0000000..d507e06 --- /dev/null +++ b/docs/use-case-publishing.md @@ -0,0 +1,286 @@ +# Use Case: A Simple and Powerful Publishing Platform + +This repository is pre-configured to act as a simple, powerful, and free website publishing platform using GitHub Pages. This guide walks you through how to use it to create and manage your own site. + +## Part 1: Choosing Your Website's Design + +Your website's look and feel is controlled by a "theme". This repository uses Jekyll, a static site generator, which has great support for themes. + +### How to Change Your Theme + +You can change your website's theme with a single line of code. + +1. Open the [`_config.yml`](../_config.yml) file in the root of your repository. +2. You will see a line: `theme: jekyll-theme-primer`. +3. To change the theme, simply replace `jekyll-theme-primer` with the name of another supported theme. For example: `theme: jekyll-theme-minimal`. +4. Commit the change, and your site will be rebuilt with the new theme. + +### Supported Themes + +GitHub Pages officially supports a number of themes. You can preview them by visiting their repositories. + +| Theme Name | How to Use It ([`_config.yml`](../_config.yml)) | Preview Link | +| :----------- | :---------------------------------------------- | :------------------------------------------------------------- | +| Architect | `theme: jekyll-theme-architect` | [View on GitHub](https://github.com/pages-themes/architect) | +| Cayman | `theme: jekyll-theme-cayman` | [View on GitHub](https://github.com/pages-themes/cayman) | +| Dinky | `theme: jekyll-theme-dinky` | [View on GitHub](https://github.com/pages-themes/dinky) | +| Hacker | `theme: jekyll-theme-hacker` | [View on GitHub](https://github.com/pages-themes/hacker) | +| Leap Day | `theme: jekyll-theme-leap-day` | [View on GitHub](https://github.com/pages-themes/leap-day) | +| Merlot | `theme: jekyll-theme-merlot` | [View on GitHub](https://github.com/pages-themes/merlot) | +| Midnight | `theme: jekyll-theme-midnight` | [View on GitHub](https://github.com/pages-themes/midnight) | +| Minimal | `theme: jekyll-theme-minimal` | [View on GitHub](https://github.com/pages-themes/minimal) | +| Modernist | `theme: jekyll-theme-modernist` | [View on GitHub](https://github.com/pages-themes/modernist) | +| Primer | `theme: jekyll-theme-primer` | [View on GitHub](https://github.com/pages-themes/primer) | +| Slate | `theme: jekyll-theme-slate` | [View on GitHub](https://github.com/pages-themes/slate) | +| Tactile | `theme: jekyll-theme-tactile` | [View on GitHub](https://github.com/pages-themes/tactile) | +| Time Machine | `theme: jekyll-theme-time-machine` | [View on GitHub](https://github.com/pages-themes/time-machine) | + +### Advanced: Using Other Themes + +You are not limited to the themes above. Using the `remote_theme` option, you can use almost any public Jekyll theme hosted on GitHub. + +To do this, change your [`_config.yml`](../_config.yml) to use `remote_theme` instead of `theme`, and provide the theme's repository name. + +```yaml +# remote_theme: owner/repository-name +remote_theme: jekyll/minima +``` + +### Advanced: Customizing a Theme's CSS + +If you want to add your own custom styles without creating a whole new theme, you can override the theme's CSS. + +1. Create a file named `/assets/css/style.scss`. +2. Add the following lines to the top of the file. This imports the theme's default stylesheet. + + ```scss + --- + --- + + @import "{{ site.theme }}"; + ``` + +3. Below the `@import` line, you can add any custom CSS you want. + +## Part 2: Creating and Editing Content + +### The Publishing Workflow + +Publishing is as simple as editing text files. + +1. **Edit or Create Files:** Edit an existing Markdown (`.md`) file or create a new one. +2. **Commit and Push:** Save and push your changes to the `main` branch. +3. **Done!** The website will automatically rebuild and your changes will be live in a minute or two. + +### Homepage and Other Pages + +- **Homepage:** The content of your site's homepage is the [`README.md`](../README.md) file. +- **Other Pages:** Any other `.md` file in your repository becomes a page on your site. For example, `contact.md` will be available at `your-site.com/contact`. + +### Working with Markdown and HTML + +This publishing platform fully supports both Markdown (`.md`) and standard HTML (`.html`) files. You can choose to write your pages in either format. + +- **For simple content**, like blog posts or basic documentation, Markdown is usually faster and easier to write. +- **For complex layouts** that require specific HTML structures or CSS classes, you can write the page directly in HTML. + +You can create new `.html` files or add existing ones to the repository, and they will be published as pages on your site. + +### Organizing Your Site + +You can create folders to organize your content. A file at `docs/about.md` will be available at `your-site.com/docs/about`. + +To link between pages, use relative links in your Markdown. + +It's best to use paths relative to the current file (e.g., starting with `./` or `../`). This ensures the links work correctly both when browsing the repository on the GitHub website and on your final published GitHub Pages site. + +For example, from your root [`README.md`](../README.md), you could link to a file in `docs` like this: + +```markdown +[Read our About page](./docs/about.md) +``` + +## Part 3: Mastering Your Content with Advanced Formatting + +Markdown is designed to be simple, but it has powerful features for creating rich content. + +### Code Blocks with Syntax Highlighting + +You can create code blocks by wrapping your code in triple backticks. You can also specify the language for syntax highlighting. + +````markdown +```javascript +function helloWorld() { + console.log("Hello, world!"); +} +``` +```` + +### Tables + +You can create tables to organize data. + +```markdown +| Feature | Support Level | Notes | +| :-------------- | :-----------: | :---------------------------------- | +| Themes | Good | Several supported themes available. | +| Advanced HTML | Limited | Only whitelisted tags are allowed. | +| Markdown Tables | Excellent | Full support for GFM tables. | +``` + +### Task Lists + +Create checklists in your content. + +```markdown +- [x] Draft the documentation. +- [ ] Add more examples. +- [ ] Request a review. +``` + +### Alerts and Blockquotes + +You can use a special blockquote syntax to create styled "alerts" that highlight important information. + +```markdown +> [!NOTE] +> This is a note. It contains useful information users should know. + +> [!WARNING] +> This is a warning. It advises about risks or negative outcomes. +``` + +### Working with Images and Videos + +You can easily include images and videos to make your content more engaging. + +#### Images + +The standard Markdown syntax for an image is `![Alt Text](URL)`. + +- **Local Images:** If you add an image to your repository (e.g., in an `assets` folder), you can link to it with a relative path. + ```markdown + ![A diagram of our process](./assets/process-diagram.png) + ``` +- **Remote Images:** You can also link directly to an image hosted on another website. + ```markdown + ![A photo of the earth from space](https://example.com/path/to/earth.jpg) + ``` + +#### Embedding Videos + +While you can't embed a video player directly into a Markdown file, you can use a clever trick to create a clickable thumbnail that links to the video. This is the best way to include YouTube videos. + +1. Find your YouTube video's ID. It's the string of characters at the end of the URL (e.g., `iadzYtX4ERU`). +2. Use the following Markdown snippet, replacing `YOUTUBE_VIDEO_ID_HERE` with your video's ID. + +```markdown +[![Watch the video](https://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg)](https://www.youtube.com/watch?v=YOUTUBE_VIDEO_ID_HERE) +``` + +This code displays the video's thumbnail image and makes it a link to the video on YouTube. + +### Page Titles and SEO + +By default, GitHub Pages uses a plugin called `jekyll-seo-tag` to automatically add common search engine optimization (SEO) metadata to your site. You can control this metadata to improve how your site appears in search results and on social media. + +#### Setting the Title and Description for a Single Page + +To set a custom title and description for a specific page, add a "front matter" block to the very top of your `.md` file. Front matter is a block of YAML code between two `---` lines. + +For example, you could add this to the top of a file named `about.md`: + +```yaml +--- +title: About Our Company +description: Learn about our history, our team, and our mission. +image: /assets/our-team-photo.jpg +--- +# About Us + +This is the rest of your page content... +``` + +- `title`: This will be used for the page's `` tag (what you see in the browser tab). +- `description`: This will be used for the page's meta description (the snippet shown in search results). +- `image`: If you provide a path to an image, it will be used for social media previews (e.g., when you share the link on Twitter or Facebook). + +#### Setting a Site-Wide Title and Description + +You can also set a default title and description for your entire site in the [`_config.yml`](../_config.yml) file. + +```yaml +title: My Awesome Project +description: A website about my awesome project and other cool things. +``` + +The page-specific front matter will always override the site-wide settings in `_config.yml`. + +### Using HTML for More Control + +While most HTML tags are stripped for security, GitHub Pages allows a "whitelist" of safe tags for advanced formatting. This means you can't use just any HTML, but you can do some cool things. + +A great example is creating a collapsible section using `<details>` and `<summary>`. + +```html +<details> + <summary>Click here to see the details!</summary> + + This content is hidden until you click the summary. You can put any Markdown + content in here, including lists, code blocks, or images. +</details> +``` + +Other useful HTML tags that are generally allowed include `<sub>` for <sub>subscript</sub>, `<sup>` for <sup>superscript</sup>, and `<kbd>` for styling keyboard inputs like <kbd>Ctrl</kbd>+<kbd>C</kbd>. + +--- + +## Understanding the Limitations + +GitHub Pages is a powerful tool, but it's important to understand its limitations. + +- **Static Sites Only:** This is the most important limitation. GitHub Pages cannot run server-side code (like PHP, Python, or a database). It can only serve static files: HTML, CSS, JavaScript, images, etc. This means you cannot have features like a user login system, a shopping cart, or a server-side contact form. + +- **Usage Limits:** For repositories on the free plan, GitHub Pages has some soft limits: + - **Size:** Your repository should ideally stay under 1GB. + - **Bandwidth:** Your site has a soft limit of 100GB of bandwidth per month. + - **Builds:** Your site will be rebuilt up to 10 times per hour. Pushing many small commits in a short period might cause some builds to be skipped. + +- **No Custom Jekyll Plugins:** GitHub Pages only supports a specific list of Jekyll plugins. You cannot use custom or third-party plugins that are not on [this list](https://pages.github.com/versions/). + +- **Site Visibility:** If your repository is public, your GitHub Pages site will be public. If your repository is private, your site will also be public unless you have a paid GitHub plan (Pro, Team, or Enterprise). + +--- + +## Advanced Topics + +### Previewing Your Site Locally + +The default workflow is to push changes to your `main` branch and wait for GitHub to publish them. For larger changes, you may want to preview your site on your own computer before publishing. + +This is possible, but it is an advanced topic that requires installing some software on your machine (specifically, Ruby and Jekyll). + +While the setup can be technical, the benefit is that you can run a local web server that behaves exactly like GitHub Pages. You can see your changes instantly at `http://localhost:4000` without having to commit and push every time. + +To learn how to do this, follow the official guide from GitHub: + +- **[Testing your GitHub Pages site locally with Jekyll](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll)** + +### Creating a Navigation Menu + +Many themes allow you to create a persistent navigation menu at the top of your site (e.g., "Home | About | Contact"). The implementation details depend on the theme, but it is often configured in the [`_config.yml`](../_config.yml) file. + +For example, the popular "Minima" theme looks for a `header_pages` array in your `_config.yml`: + +```yaml +# In _config.yml +header_pages: + - about.md + - contact.md +``` + +This would create a navigation menu with links to your "About" and "Contact" pages. + +The default `primer` theme does not support this feature out-of-the-box. To add a navigation menu, you will need to switch to a different theme or add your own custom HTML layout. + +**Always check the documentation for your chosen theme** to see what navigation features it supports and how to configure them.