Skip to content

Commit 99e3a40

Browse files
noraworldnoraworld
committed
Add README for Japanese
This fixes #11
1 parent 7cb850a commit 99e3a40

File tree

3 files changed

+341
-170
lines changed

3 files changed

+341
-170
lines changed

‎README.md‎

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

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
README/en.md

‎README/en.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# GitHub-to-Qiita
2+
GitHub-to-Qiita lets you integrate your Qiita articles with your GitHub repository. Setting up GitHub-to-Qiita and pushing your articles into your GitHub repository, they will be published to [Qiita](https://qiita.com) automatically.
3+
4+
Make your writing efficient and save your time with GitHub-to-Qiita! 😉
5+
6+
7+
8+
## Setup
9+
The setup is easy. You can setup a workflow by following the instructions below.
10+
11+
### Generate a Qiita access token
12+
Navigate to [the Qiita access token generation page](https://qiita.com/settings/tokens/new).
13+
14+
![](screenshots/generate_qiita_access_token.png)
15+
16+
Enter the following information, and click the `Generate token` button.
17+
18+
| Key | Description | Fixed | Sample or Fixed Value |
19+
| ----------- | ------------------------------------------------------------------------------------------- | ----- | ------------------------------ |
20+
| Description | Specify a description so you are easy to understand for what the access token is used later | false | `GitHub to Qiita` |
21+
| Scopes | Specify scopes that describe what privilege the access token has | true | `read_qiita` and `write_qiita` |
22+
23+
After generating your new access token, it should be going to appear on your screen. Then copy it.
24+
25+
![](screenshots/qiita_access_token.png)
26+
27+
Note that it can be shown only once. If you lose it, regenerate it again.
28+
29+
**WARNING:** The above screen shot shows a dummy access token, not a real access token. You should not take a screen shot including your access token, and must not share it with other people. Please be careful.
30+
31+
### Set your Qiita access token to your repository
32+
Navigate to the Actions secrets creation page, which is accessible at `https://github.com/<USERNAME>/<REPONAME>/settings/secrets/actions/new`.
33+
34+
![](screenshots/actions_secrets.png)
35+
36+
Enter the following information, and click the `Add secret` button.
37+
38+
| Key | Description | Sample Value |
39+
| ----- | ------------------------------------------------------------------------- | --------------------------------------------------------------- |
40+
| Name | Specify your secret environment variable name for your Qiita access token | `QIITA_ACCESS_TOKEN` |
41+
| Value | Specify your Qiita access token | `7ace9cfa98815ed3d5cd1e1bba8e745c152e9071` (THIS IS A SAMPLE!!) |
42+
43+
### Create a workflow file
44+
Create a file as `.github/workflows/qiita.yml`, and set your own workflow.
45+
46+
Here is a sample workflow.
47+
48+
```yaml
49+
# .github/workflows/qiita.yml
50+
51+
name: "GitHub to Qiita"
52+
53+
on:
54+
push:
55+
branches: [ main ]
56+
57+
jobs:
58+
qiita:
59+
runs-on: ubuntu-latest
60+
steps:
61+
- name: "Publish to Qiita"
62+
uses: noraworld/[email protected]
63+
with:
64+
dir: "articles"
65+
qiita_access_token: ${{ secrets.QIITA_ACCESS_TOKEN }}
66+
```
67+
68+
Replace a part of the above YAML code with the following.
69+
70+
| Key | Description | Required | Sample or Default Value |
71+
| --------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- | ----------------------------------- |
72+
| `jobs.qiita.steps[*].with.dir` | Specify a directory in which files you want to track and publish to Qiita | true | `articles` |
73+
| `jobs.qiita.steps[*].with.qiita_access_token` | Specify your Qiita access token (accessible by `${{ secrets.QIITA_ACCESS_TOKEN }}` [^1]) | true | `${{ secrets.QIITA_ACCESS_TOKEN }}` |
74+
| `jobs.qiita.steps[*].with.mapping_filepath` | Specify any file path in which you want to put the mapping file | false | `mapping.txt` |
75+
76+
[^1]: Only in case you set the secret environment variable name as `QIITA_ACCESS_TOKEN` at the previous step.
77+
78+
**WARNING:** Please do not set the version to `@main` at the `jobs.qiita.steps[*].uses` section for a production use because the specification is subject to change, and the latest codes potentially contain bugs. It is highly recommended to set the latest tagged version, which can be accessible at the [Tags page](/../../tags).
79+
80+
---
81+
82+
That’s all!
83+
84+
85+
86+
## Syntax
87+
Your Markdown articles need to include a YAML header like this.
88+
89+
```yaml
90+
---
91+
title: "Your awesome title"
92+
topics: ["GitHub Actions", "Ruby", "YAML"]
93+
published: true
94+
---
95+
96+
Your article starts here.
97+
```
98+
99+
| Key | Description | Type | Constraint |
100+
| ----------- | --------------------------------------------------------------- | -------------------------------------- | ------------ |
101+
| `title` | Specify a title of an article | `String` | |
102+
| `topics` | Specify tags of an article that describes its attributes | `Array[String, <String, String, ...>]` | Up to 5 tags |
103+
| `published` | Specify whether an article will be posted publicly or privately | `Boolean` | |
104+
105+
Note that your article file must start with `---`.
106+
107+
Additional keys and values are acceptable. They are simply ignored.
108+
109+
110+
111+
## How it works
112+
Pushing your articles in the specific directory (`articles` directory in the sample workflow above) into the specific branch (`main` branch in the sample workflow above), it starts to work automatically. There is no need to do the further operation.
113+
114+
You can see whether your workflow succeeded at `https://github.com/<USERNAME>/<REPONAME>/actions/workflows/qiita.yml`.
115+
116+
117+
118+
## How to contribute
119+
The files and directories for a local development are as follow.
120+
121+
* `.env`
122+
* `mapping.txt`
123+
* `articles/`
124+
125+
These are ignored for Git (described in `.gitignore`), so you can create sample data and use them to test how it works.
126+
127+
**WARNING:** The `published` key in a YAML header in a sample article (files in `articles/`) should be always set to `false`, or your sample article will be exposed publicly!
128+
129+
```yaml
130+
---
131+
title: "Test"
132+
topics: ["Foo", "Bar", "Baz"]
133+
published: false # <= IMPORTANT!!!
134+
---
135+
136+
This is a test article.
137+
```
138+
139+
### Environment variables
140+
You need to set the following environment variables for a local debug. Note that the environment variables in `.env` are loaded only when a development environment.
141+
142+
Here is a sample `.env` file.
143+
144+
```ruby
145+
ADDED_FILES="articles/test01.md"
146+
MODIFIED_FILES="articles/test02.md"
147+
MAPPING_FILEPATH="mapping.txt"
148+
QIITA_ACCESS_TOKEN="7f6c7aec310ded84ae3acfe8f920cb1c7556c7d3" # THIS IS A SAMPLE!!
149+
```
150+
151+
| Environment Variable Name | Description | Required |
152+
| ------------------------- | ---------------------------------------------------------- | -------- |
153+
| `ADDED_FILES` | Paths of articles that will be published newly | false |
154+
| `MODIFIED_FILES` | Paths of articles that will be modified | false |
155+
| `MAPPING_FILEPATH` | A filepath to which file it writes the mapping information | true |
156+
| `QIITA_ACCESS_TOKEN` | Your Qiita access token (for development) | true |
157+
158+
**NOTE:** It is highly recommended to use the Qiita access token that is different from one for a production use.
159+
160+
You can omit either `ADDED_FILES` or `MODIFIED_FILES`, but if both are omitted, it does nothing.
161+
162+
163+
164+
## Notice
165+
The old implementation has moved to [noraworld/github-to-qiita-server](https://github.com/noraworld/github-to-qiita-server), and it is no longer maintained.
166+
167+
168+
169+
## License
170+
All codes of this repository are available under the MIT license. See the [LICENSE](/LICENSE) for more information.

0 commit comments

Comments
 (0)