Skip to content

Commit d852044

Browse files
google-labs-jules[bot]google-labs-jules[bot]
committed
Chore: Refactor publishing docs based on feedback
This commit refactors the publishing documentation in response to user feedback. - Renamed `linking.add-story.md` to `publishing.magic-links.md` and moved it into the "Publishing" category. - Generalized the content of the magic links guide. - Restructured the core publishing guides: - `publishing.md` is now a high-level overview. - The simple Markdown guide has been moved to `publishing.markdown.md`. - Updated the `docs/README.md` index to reflect these changes.
1 parent fbff1a4 commit d852044

5 files changed

Lines changed: 217 additions & 183 deletions

File tree

‎docs/README.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,6 @@ This directory contains the documentation for the `base` project.
3838
## Documentation
3939

4040
- `[documentation.best-practices.md](./documentation.best-practices.md)` - Documentation Best Practices - How to write clear and effective documentation.
41-
- `[linking.add-story.md](./linking.add-story.md)` - "Add Your Story" Links - Creating links that pre-fill new file content.
4241

4342
## Guides
4443

@@ -56,6 +55,8 @@ This directory contains the documentation for the `base` project.
5655

5756
## Publishing
5857

59-
- `[publishing.md](./publishing.md)` - Publishing with Markdown - A simple guide to creating your own website.
60-
- `[publishing.html.md](./publishing.html.md)` - Advanced Publishing - Using HTML, local previews, and more.
61-
- `[publishing.github-pages.md](./publishing.github-pages.md)` - GitHub Pages - How documentation is built and deployed.
58+
- `[publishing.md](./publishing.md)` - Publishing Overview - An overview of the different ways to publish content.
59+
- `[publishing.markdown.md](./publishing.markdown.md)` - Publishing with Markdown - The simplest way to create pages.
60+
- `[publishing.html.md](./publishing.html.md)` - Advanced Publishing with HTML - For more control over layout and style.
61+
- `[publishing.magic-links.md](./publishing.magic-links.md)` - Publishing with Magic Links - Creating links that pre-fill new file content.
62+
- `[publishing.github-pages.md](./publishing.github-pages.md)` - GitHub Pages - How the underlying publishing system works.

‎docs/linking.add-story.md‎

Lines changed: 0 additions & 48 deletions
This file was deleted.

‎docs/publishing.magic-links.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Publishing with Magic Links
2+
3+
"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.
4+
5+
## How They Work
6+
7+
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.
8+
9+
Here is a generic example of what the Markdown for a magic link might look like:
10+
11+
```markdown
12+
[<kbd>Click Here to Add a New Item</kbd>](https://github.com/{OWNER}/{REPO}/new/{BRANCH}/?filename={PATH_TO_FILE}&value={URL_ENCODED_CONTENT})
13+
```
14+
15+
### Key Parameters
16+
17+
- `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.
18+
- `value`: This contains the URL-encoded content that will pre-fill the new file.
19+
20+
## Deconstructing the `value` Parameter
21+
22+
The `value` parameter is the core of the magic link. It's your template, but URL-encoded.
23+
24+
Here is an example of a decoded template for a simple blog post:
25+
26+
```yaml
27+
---
28+
layout: post
29+
title: "[YOUR TITLE HERE]"
30+
date: YYYY-MM-DD
31+
description: "[A one-sentence summary of your post]"
32+
author: "[Your Name or GitHub Username]"
33+
---
34+
35+
[YOUR FULL CONTENT HERE. Write as much as you want!]
36+
37+
**How to add images:**
38+
1. After creating this file, drag & drop your images into this folder.
39+
2. Link to them with `![Image description](./your-image-name.png)`
40+
```
41+
42+
This example uses a standard Jekyll post format with YAML front matter. The placeholders guide the user on what to fill in.
43+
44+
## How to Create Your Own Magic Link
45+
46+
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.
47+
48+
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.
49+
50+
3. **Construct the Final URL:** Assemble the link by combining the base URL and your parameters.
51+
- **Base URL:** `https://github.com/{OWNER}/{REPO}/new/{BRANCH}/`
52+
- Replace `{OWNER}`, `{REPO}`, and `{BRANCH}` with your repository's information.
53+
- **Filename:** `?filename=path/to/your/new-file.md`
54+
- Define the path and name for the new file.
55+
- **Value:** `&value={YOUR_ENCODED_CONTENT}`
56+
- Paste your URL-encoded template content here.
57+
58+
4. **Create the Markdown Link:** For easy use, embed your final URL into a Markdown link. Using `<kbd>` tags can make the link appear more like a button, which can improve user experience.
59+
60+
```markdown
61+
[<kbd>Click Here to Contribute</kbd>](YOUR_FINAL_URL)
62+
```

‎docs/publishing.markdown.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Publishing with Markdown
2+
3+
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.
4+
5+
## Part 1: Choosing Your Website's Design
6+
7+
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.
8+
9+
### How to Change Your Theme
10+
11+
You can change your website's theme with a single line of code.
12+
13+
1. Open the `_config.yml` file in the root of your repository.
14+
2. You will see a line: `theme: jekyll-theme-primer`.
15+
3. To change the theme, simply replace `jekyll-theme-primer` with the name of another supported theme. For example: `theme: jekyll-theme-minimal`.
16+
4. Commit the change, and your site will be rebuilt with the new theme.
17+
18+
### Supported Themes
19+
20+
GitHub Pages officially supports a number of themes. You can preview them by visiting their repositories.
21+
22+
| Theme Name | How to Use It (`_config.yml`) | Preview Link |
23+
| :----------- | :---------------------------------------------- | :------------------------------------------------------------- |
24+
| Architect | `theme: jekyll-theme-architect` | [View on GitHub](https://github.com/pages-themes/architect) |
25+
| Cayman | `theme: jekyll-theme-cayman` | [View on GitHub](https://github.com/pages-themes/cayman) |
26+
| Dinky | `theme: jekyll-theme-dinky` | [View on GitHub](https://github.com/pages-themes/dinky) |
27+
| Hacker | `theme: jekyll-theme-hacker` | [View on GitHub](https://github.com/pages-themes/hacker) |
28+
| Leap Day | `theme: jekyll-theme-leap-day` | [View on GitHub](https://github.com/pages-themes/leap-day) |
29+
| Merlot | `theme: jekyll-theme-merlot` | [View on GitHub](https://github.com/pages-themes/merlot) |
30+
| Midnight | `theme: jekyll-theme-midnight` | [View on GitHub](https://github.com/pages-themes/midnight) |
31+
| Minimal | `theme: jekyll-theme-minimal` | [View on GitHub](https://github.com/pages-themes/minimal) |
32+
| Modernist | `theme: jekyll-theme-modernist` | [View on GitHub](https://github.com/pages-themes/modernist) |
33+
| Primer | `theme: jekyll-theme-primer` | [View on GitHub](https://github.com/pages-themes/primer) |
34+
| Slate | `theme: jekyll-theme-slate` | [View on GitHub](https://github.com/pages-themes/slate) |
35+
| Tactile | `theme: jekyll-theme-tactile` | [View on GitHub](https://github.com/pages-themes/tactile) |
36+
| Time Machine | `theme: jekyll-theme-time-machine` | [View on GitHub](https://github.com/pages-themes/time-machine) |
37+
38+
## Part 2: Creating and Editing Content
39+
40+
### The Publishing Workflow
41+
42+
Publishing is as simple as editing text files.
43+
44+
1. **Edit or Create Files:** Edit an existing Markdown (`.md`) file or create a new one.
45+
2. **Commit and Push:** Save and push your changes to the `main` branch.
46+
3. **Done!** The website will automatically rebuild and your changes will be live in a minute or two.
47+
48+
### Homepage and Other Pages
49+
50+
- **Homepage:** The content of your site's homepage is the `README.md` file in the root of the repository.
51+
- **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`.
52+
53+
### Organizing Your Site
54+
55+
You can create folders to organize your content. A file at `docs/about.md` will be available at `your-site.com/docs/about`.
56+
57+
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 `../`).
58+
59+
For example, from your root `README.md`, you could link to a file in `docs` like this:
60+
61+
```markdown
62+
[Read our About page](./docs/about.md)
63+
```
64+
65+
## Part 3: Advanced Formatting
66+
67+
Markdown is designed to be simple, but it has powerful features for creating rich content.
68+
69+
### Code Blocks with Syntax Highlighting
70+
71+
````markdown
72+
```javascript
73+
function helloWorld() {
74+
console.log("Hello, world!");
75+
}
76+
```
77+
````
78+
79+
### Tables
80+
81+
```markdown
82+
| Feature | Support Level | Notes |
83+
| :-------------- | :-----------: | :---------------------------------- |
84+
| Themes | Good | Several supported themes available. |
85+
| Markdown Tables | Excellent | Full support for GFM tables. |
86+
```
87+
88+
### Task Lists
89+
90+
```markdown
91+
- [x] Draft the documentation.
92+
- [ ] Add more examples.
93+
- [ ] Request a review.
94+
```
95+
96+
### Alerts and Blockquotes
97+
98+
```markdown
99+
> [!NOTE]
100+
> This is a note. It contains useful information users should know.
101+
102+
> [!WARNING]
103+
> This is a warning. It advises about risks or negative outcomes.
104+
```
105+
106+
### Working with Images and Videos
107+
108+
#### Images
109+
110+
The standard Markdown syntax for an image is `![Alt Text](URL)`.
111+
112+
- **Local Images:** `![A diagram of our process](./assets/process-diagram.png)`
113+
- **Remote Images:** `![A photo of the earth from space](https://example.com/path/to/earth.jpg)`
114+
115+
#### Embedding Videos
116+
117+
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.
118+
119+
```markdown
120+
[![Watch the video](https://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg)](https://www.youtube.com/watch?v=YOUTUBE_VIDEO_ID_HERE)
121+
```
122+
123+
### Page Titles and SEO
124+
125+
To set a custom title and description for a specific page, add a "front matter" block to the very top of your `.md` file.
126+
127+
```yaml
128+
---
129+
title: About Our Company
130+
description: Learn about our history, our team, and our mission.
131+
image: /assets/our-team-photo.jpg
132+
---
133+
# About Us
134+
135+
This is the rest of your page content...
136+
```
137+
138+
You can also set a site-wide title and description in the `_config.yml` file.

0 commit comments

Comments
 (0)