diff --git a/assets/logo1.svg b/assets/logo1.svg new file mode 100644 index 0000000..92662bf --- /dev/null +++ b/assets/logo1.svg @@ -0,0 +1,4 @@ + + Logo 1: Solid Square + + diff --git a/assets/logo2.svg b/assets/logo2.svg new file mode 100644 index 0000000..5b5bbf7 --- /dev/null +++ b/assets/logo2.svg @@ -0,0 +1,7 @@ + + Logo 2: Nested Squares + + + + + diff --git a/assets/logo3.svg b/assets/logo3.svg new file mode 100644 index 0000000..4b6b615 --- /dev/null +++ b/assets/logo3.svg @@ -0,0 +1,5 @@ + + Logo 3: Stylized B + + + diff --git a/assets/logo4.svg b/assets/logo4.svg new file mode 100644 index 0000000..1b0461d --- /dev/null +++ b/assets/logo4.svg @@ -0,0 +1,7 @@ + + Logo 4: Rocket Ship + + + + + diff --git a/assets/logo5.svg b/assets/logo5.svg new file mode 100644 index 0000000..ab3de8b --- /dev/null +++ b/assets/logo5.svg @@ -0,0 +1,6 @@ + + Logo 5: Stack of Blocks + + + + diff --git a/docs/README.md b/docs/README.md index b540477..bdebb9b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,30 +2,61 @@ This directory contains the documentation for the `base` project. -- **[The `base` Philosophy](./base.md)**: An overview of the core principles and goals behind this template repository. -- **[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. -- **[Use Case: A Software Project](./use-case-software-project.md)**: A guide to using this repository as a foundation for your own software project. -- **[Prompting AI Agents](./prompting-ai-agents.md)**: A guide on how to effectively prompt AI agents when working on `base`-based projects. -- **[Guiding AI with `AGENTS.md`](./agents-md-guide.md)**: An explanation of how to use the `AGENTS.md` file to provide persistent instructions to AI agents. -- **[The `package.json` files](./package-json-guide.md)**: An explanation of the `package.json` and `package-lock.json` files used for development tooling. -- **[GitHub Workflows](./github-workflows.md)**: An explanation of the CI/CD workflows for linting, testing, and releasing. -- **[Manually Formatting Code with the Prettier Workflow](./prettier-workflow.md)**: A guide to using the manually-triggered workflow to format the codebase. -- **[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. -- **[Merging `base` Into an Existing Repository](./merging-base.md)**: A guide on how to incorporate `base` into an existing project. -- **[Standard Repository Files](./standard-files.md)**: An explanation of the standard configuration files like `.gitignore`, `.editorconfig`, and `.gitattributes`. -- **[Using Prettier](./prettier.md)**: A guide to installing and using Prettier for code formatting. -- **[Repository Badges](./badges.md)**: An explanation of how to use and create repository badges. -- **[Maintaining `base` as a Template Repository](./template-repo.md)**: A guide for maintainers of this template, outlining best practices and administrative steps. -- **[Versioning and Release Management](./versioning-guide.md)**: A guide to professional release management using Semantic Versioning and GitHub's automated release notes feature. -- **[Community Building Guide](./community-building-guide.md)**: Best-practice advice on how to foster a healthy, welcoming, and effective community around a new open-source project. -- **[Project Launch Checklist](./launch-checklist.md)**: A reusable checklist for ensuring a smooth and successful project launch. -- **[Secrets Management in GitHub Actions](./secrets-management.md)**: A guide on the best practice of using GitHub Actions secrets to manage sensitive credentials. -- **[Scheduling Workflows with Cron](./workflow-scheduling.md)**: A tutorial on how to use cron scheduling within GitHub Actions to automate recurring tasks. -- **[Issue Management Guide](./issue-management-guide.md)**: A guide to best practices for triaging bug reports and feature requests using GitHub Issues. -- **[Documentation Best Practices](./documentation-best-practices.md)**: A tutorial on the art of writing clear and effective documentation. -- **[Using GitHub Discussions](./using-github-discussions.md)**: A guide on how to leverage GitHub Discussions for community conversations. -- **[Security Best Practices for Maintainers](./security-best-practices.md)**: A guide covering basic security practices for open-source maintainers. +- `[base.md](./base.md)` - The `base` Philosophy - An overview of the core principles and goals of this template. +- `[README.md](./README.md)` - Documentation Index - You are here. + +## AI + +- `[ai.agents-md.md](./ai.agents-md.md)` - Guiding AI with `AGENTS.md` - Using `AGENTS.md` to provide instructions to AI agents. +- `[ai.prompting.md](./ai.prompting.md)` - Prompting AI Agents - How to effectively prompt AI agents. + +## CI/CD + +- `[cicd.secrets-management.md](./cicd.secrets-management.md)` - Secrets Management - Best practices for managing secrets in GitHub Actions. +- `[cicd.workflow-scheduling.md](./cicd.workflow-scheduling.md)` - Workflow Scheduling - Automating recurring tasks with cron. +- `[cicd.workflows.md](./cicd.workflows.md)` - GitHub Workflows - Explanation of the CI/CD workflows. + +## Community + +- `[community.building.md](./community.building.md)` - Community Building Guide - Fostering a healthy and effective community. +- `[community.discussions.md](./community.discussions.md)` - Using GitHub Discussions - Leveraging Discussions for community conversations. +- `[community.issue-management.md](./community.issue-management.md)` - Issue Management Guide - Best practices for triaging issues. + +## Deployment + +- `[deployment.render.md](./deployment.render.md)` - Deploying to Render.com - Instructions for deploying to Render.com. + +## Development + +- `[development.codespaces.md](./development.codespaces.md)` - GitHub Codespaces - Using Codespaces for cloud-based development. +- `[development.docker.md](./development.docker.md)` - Docker Environment - Using the included Docker setup. +- `[development.merging-base.md](./development.merging-base.md)` - Merging `base` - Incorporating `base` into an existing project. +- `[development.package-json.md](./development.package-json.md)` - `package.json` Guide - Explanation of the `package.json` files. +- `[development.prettier.md](./development.prettier.md)` - Using Prettier - Guide to installing and using Prettier. +- `[development.prettier-workflow.md](./development.prettier-workflow.md)` - Prettier Workflow - Manually formatting code. + +## Documentation + +- `[documentation.best-practices.md](./documentation.best-practices.md)` - Documentation Best Practices - How to write clear and effective documentation. + +## Guides + +- `[guides.software-project.md](./guides.software-project.md)` - Software Project Guide - Using this repo as a foundation for a software project. + +## Project Management + +- `[project.badges.md](./project.badges.md)` - Repository Badges - How to use and create repository badges. +- `[project.launch-checklist.md](./project.launch-checklist.md)` - Launch Checklist - A reusable checklist for project launches. +- `[project.licensing.md](./project.licensing.md)` - Licensing Info - Details on the MIT License. +- `[project.security.md](./project.security.md)` - Security Best Practices - Basic security practices for maintainers. +- `[project.standard-files.md](./project.standard-files.md)` - Standard Files - Explanation of standard repo files. +- `[project.template-repo.md](./project.template-repo.md)` - Template Repo Guide - Best practices for maintaining this template. +- `[project.versioning.md](./project.versioning.md)` - Versioning Guide - Professional release management. + +## Publishing + +- `[publishing.md](./publishing.md)` - Publishing Overview - An overview of the different ways to publish content. +- `[publishing.markdown.md](./publishing.markdown.md)` - Publishing with Markdown - The simplest way to create pages. +- `[publishing.html.md](./publishing.html.md)` - Advanced Publishing with HTML - For more control over layout and style. +- `[publishing.magic-links.md](./publishing.magic-links.md)` - Publishing with Magic Links - Creating links that pre-fill new file content. +- `[publishing.github-pages.md](./publishing.github-pages.md)` - GitHub Pages - How the underlying publishing system works. diff --git a/docs/agents-md-guide.md b/docs/ai.agents-md.md similarity index 100% rename from docs/agents-md-guide.md rename to docs/ai.agents-md.md diff --git a/docs/prompting-ai-agents.md b/docs/ai.prompting.md similarity index 100% rename from docs/prompting-ai-agents.md rename to docs/ai.prompting.md diff --git a/docs/secrets-management.md b/docs/cicd.secrets-management.md similarity index 100% rename from docs/secrets-management.md rename to docs/cicd.secrets-management.md diff --git a/docs/workflow-scheduling.md b/docs/cicd.workflow-scheduling.md similarity index 100% rename from docs/workflow-scheduling.md rename to docs/cicd.workflow-scheduling.md diff --git a/docs/github-workflows.md b/docs/cicd.workflows.md similarity index 100% rename from docs/github-workflows.md rename to docs/cicd.workflows.md diff --git a/docs/community-building-guide.md b/docs/community.building.md similarity index 100% rename from docs/community-building-guide.md rename to docs/community.building.md diff --git a/docs/using-github-discussions.md b/docs/community.discussions.md similarity index 100% rename from docs/using-github-discussions.md rename to docs/community.discussions.md diff --git a/docs/issue-management-guide.md b/docs/community.issue-management.md similarity index 100% rename from docs/issue-management-guide.md rename to docs/community.issue-management.md diff --git a/docs/render.md b/docs/deployment.render.md similarity index 100% rename from docs/render.md rename to docs/deployment.render.md diff --git a/docs/github-codespaces.md b/docs/development.codespaces.md similarity index 100% rename from docs/github-codespaces.md rename to docs/development.codespaces.md diff --git a/docs/docker.md b/docs/development.docker.md similarity index 100% rename from docs/docker.md rename to docs/development.docker.md diff --git a/docs/merging-base.md b/docs/development.merging-base.md similarity index 100% rename from docs/merging-base.md rename to docs/development.merging-base.md diff --git a/docs/package-json-guide.md b/docs/development.package-json.md similarity index 100% rename from docs/package-json-guide.md rename to docs/development.package-json.md diff --git a/docs/prettier-workflow.md b/docs/development.prettier-workflow.md similarity index 100% rename from docs/prettier-workflow.md rename to docs/development.prettier-workflow.md diff --git a/docs/prettier.md b/docs/development.prettier.md similarity index 100% rename from docs/prettier.md rename to docs/development.prettier.md diff --git a/docs/documentation-best-practices.md b/docs/documentation.best-practices.md similarity index 100% rename from docs/documentation-best-practices.md rename to docs/documentation.best-practices.md diff --git a/docs/use-case-software-project.md b/docs/guides.software-project.md similarity index 100% rename from docs/use-case-software-project.md rename to docs/guides.software-project.md diff --git a/docs/badges.md b/docs/project.badges.md similarity index 100% rename from docs/badges.md rename to docs/project.badges.md diff --git a/docs/launch-checklist.md b/docs/project.launch-checklist.md similarity index 100% rename from docs/launch-checklist.md rename to docs/project.launch-checklist.md diff --git a/docs/licensing.md b/docs/project.licensing.md similarity index 100% rename from docs/licensing.md rename to docs/project.licensing.md diff --git a/docs/security-best-practices.md b/docs/project.security.md similarity index 100% rename from docs/security-best-practices.md rename to docs/project.security.md diff --git a/docs/standard-files.md b/docs/project.standard-files.md similarity index 100% rename from docs/standard-files.md rename to docs/project.standard-files.md diff --git a/docs/template-repo.md b/docs/project.template-repo.md similarity index 100% rename from docs/template-repo.md rename to docs/project.template-repo.md diff --git a/docs/versioning-guide.md b/docs/project.versioning.md similarity index 100% rename from docs/versioning-guide.md rename to docs/project.versioning.md diff --git a/docs/github-pages.md b/docs/publishing.github-pages.md similarity index 100% rename from docs/github-pages.md rename to docs/publishing.github-pages.md diff --git a/docs/publishing.html.md b/docs/publishing.html.md new file mode 100644 index 0000000..1391b1e --- /dev/null +++ b/docs/publishing.html.md @@ -0,0 +1,99 @@ +# Advanced Publishing: HTML, Previews, and More + +This guide covers the more advanced features of the publishing platform, including using HTML, previewing your site locally, and understanding the platform's limitations. + +## Using HTML for More Control + +While Markdown is easy to use, you can also use standard HTML (`.html`) files for your pages. This is useful for complex layouts that require specific HTML structures or CSS classes. + +You can create new `.html` files or add existing ones to the repository, and they will be published as pages on your site. + +While most HTML tags are stripped for security, GitHub Pages allows a "whitelist" of safe tags for advanced formatting. + +A great example is creating a collapsible section using `
` and ``. + +```html +
+ Click here to see the details! + + This content is hidden until you click the summary. You can put any Markdown + content in here, including lists, code blocks, or images. +
+``` + +Other useful HTML tags that are generally allowed include `` for subscript, `` for superscript, and `` for styling keyboard inputs like Ctrl+C. + +## Advanced Theming + +### Using Other Themes + +You are not limited to the themes supported by default. Using the `remote_theme` option in `_config.yml`, you can use almost any public Jekyll theme hosted on GitHub. + +```yaml +# remote_theme: owner/repository-name +remote_theme: jekyll/minima +``` + +### 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. + +--- + +## 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 and wait for GitHub to publish them. For larger changes, you may want to preview your site on your own computer before publishing. + +This requires installing 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 and see your changes instantly at `http://localhost:4000`. + +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. The implementation details depend on the theme, but it is often configured in the `_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 +``` + +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. diff --git a/docs/publishing.magic-links.md b/docs/publishing.magic-links.md new file mode 100644 index 0000000..042ac86 --- /dev/null +++ b/docs/publishing.magic-links.md @@ -0,0 +1,62 @@ +# Publishing with Magic Links + +"Magic Links" are special URLs that can pre-fill a new file in a GitHub repository with template content. This is a powerful way to encourage community contributions by making it easy for users to submit content in a structured format, such as a bug report, a testimonial, or a new blog post. + +## How They Work + +The link is a standard URL used to create a new file on GitHub, but it is enhanced with query parameters to specify a filename and pre-fill its content. + +Here is a generic example of what the Markdown for a magic link might look like: + +```markdown +[Click Here to Add a New Item](https://github.com/{OWNER}/{REPO}/new/{BRANCH}/?filename={PATH_TO_FILE}&value={URL_ENCODED_CONTENT}) +``` + +### Key Parameters + +- `filename`: This specifies the directory and name of the file to be created. You can use placeholders to guide users, for example: `_posts/YYYY-MM-DD-your-title.md`. This encourages good file naming conventions. +- `value`: This contains the URL-encoded content that will pre-fill the new file. + +## Deconstructing the `value` Parameter + +The `value` parameter is the core of the magic link. It's your template, but URL-encoded. + +Here is an example of a decoded template for a simple blog post: + +```yaml +--- +layout: post +title: "[YOUR TITLE HERE]" +date: YYYY-MM-DD +description: "[A one-sentence summary of your post]" +author: "[Your Name or GitHub Username]" +--- + +[YOUR FULL CONTENT HERE. Write as much as you want!] + +**How to add images:** +1. After creating this file, drag & drop your images into this folder. +2. Link to them with `![Image description](./your-image-name.png)` +``` + +This example uses a standard Jekyll post format with YAML front matter. The placeholders guide the user on what to fill in. + +## How to Create Your Own Magic Link + +1. **Write Your Template Content:** In a text editor, write the exact content you want to pre-fill for the user. Use clear placeholders like `[REPLACE THIS]` to indicate where they should add their own information. + +2. **URL-Encode the Content:** Your template content must be URL-encoded to be safely included in the link. This process converts special characters (like spaces, newlines, and symbols) into a format that can be transmitted over the internet. There are many free online tools available for URL encoding. Simply paste your template content into one of these tools to get the encoded version. + +3. **Construct the Final URL:** Assemble the link by combining the base URL and your parameters. + - **Base URL:** `https://github.com/{OWNER}/{REPO}/new/{BRANCH}/` + - Replace `{OWNER}`, `{REPO}`, and `{BRANCH}` with your repository's information. + - **Filename:** `?filename=path/to/your/new-file.md` + - Define the path and name for the new file. + - **Value:** `&value={YOUR_ENCODED_CONTENT}` + - Paste your URL-encoded template content here. + +4. **Create the Markdown Link:** For easy use, embed your final URL into a Markdown link. Using `` tags can make the link appear more like a button, which can improve user experience. + + ```markdown + [Click Here to Contribute](YOUR_FINAL_URL) + ``` diff --git a/docs/publishing.markdown.md b/docs/publishing.markdown.md new file mode 100644 index 0000000..8b6a5eb --- /dev/null +++ b/docs/publishing.markdown.md @@ -0,0 +1,138 @@ +# Publishing with Markdown + +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` 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`) | 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) | + +## 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` file in the root of the repository. +- **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`. + +### 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 `../`). + +For example, from your root `README.md`, you could link to a file in `docs` like this: + +```markdown +[Read our About page](./docs/about.md) +``` + +## Part 3: Advanced Formatting + +Markdown is designed to be simple, but it has powerful features for creating rich content. + +### Code Blocks with Syntax Highlighting + +````markdown +```javascript +function helloWorld() { + console.log("Hello, world!"); +} +``` +```` + +### Tables + +```markdown +| Feature | Support Level | Notes | +| :-------------- | :-----------: | :---------------------------------- | +| Themes | Good | Several supported themes available. | +| Markdown Tables | Excellent | Full support for GFM tables. | +``` + +### Task Lists + +```markdown +- [x] Draft the documentation. +- [ ] Add more examples. +- [ ] Request a review. +``` + +### Alerts and Blockquotes + +```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 + +#### Images + +The standard Markdown syntax for an image is `![Alt Text](URL)`. + +- **Local Images:** `![A diagram of our process](./assets/process-diagram.png)` +- **Remote Images:** `![A photo of the earth from space](https://example.com/path/to/earth.jpg)` + +#### Embedding Videos + +You can't embed a video player directly, but you can create a clickable thumbnail that links to the video. Replace `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) +``` + +### Page Titles and SEO + +To set a custom title and description for a specific page, add a "front matter" block to the very top of your `.md` file. + +```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... +``` + +You can also set a site-wide title and description in the `_config.yml` file. diff --git a/docs/publishing.md b/docs/publishing.md new file mode 100644 index 0000000..73373ce --- /dev/null +++ b/docs/publishing.md @@ -0,0 +1,19 @@ +# Publishing Your Project + +This repository is pre-configured to act as a simple, powerful, and free website publishing platform using GitHub Pages. There are several ways to create and manage content, from simple to advanced. + +This document provides an overview of the different methods you can use. + +## Publishing Guides + +- **[Publishing with Markdown](./publishing.markdown.md)** + - This is the simplest way to get started. If you are new to web development or just want to write and publish with minimal fuss, start here. This guide covers creating pages, formatting text, adding images, and more, all using plain Markdown files. + +- **[Advanced Publishing with HTML](./publishing.html.md)** + - For those who need more control over their site's layout and appearance, this guide explains how to use raw HTML files, customize your theme's CSS, and work with more advanced Jekyll features. It also covers the limitations of the platform. + +- **[Publishing with Magic Links](./publishing.magic-links.md)** + - This guide explains a powerful feature for community-driven sites. Learn how to create special URLs that can pre-fill a new file in your repository with template content, making it easy for users to contribute structured data like bug reports, testimonials, or blog posts. + +- **[GitHub Pages](./publishing.github-pages.md)** + - This document provides more detail on how the underlying GitHub Pages service works to automatically build and deploy your site whenever you push a change. diff --git a/docs/use-case-publishing.md b/docs/use-case-publishing.md deleted file mode 100644 index 34015c7..0000000 --- a/docs/use-case-publishing.md +++ /dev/null @@ -1,286 +0,0 @@ -# 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. diff --git a/package-lock.json b/package-lock.json index 7b6bbe6..74bb8e6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,5 +1,5 @@ { - "name": "base", + "name": "app", "lockfileVersion": 3, "requires": true, "packages": {