Skip to content

Commit

Permalink
[refactor] simplify Source Code based on DOM API & TypeScript (#23)
Browse files Browse the repository at this point in the history
  • Loading branch information
TechQuery authored Oct 14, 2023
1 parent 2dfe1bc commit 47304a8
Show file tree
Hide file tree
Showing 22 changed files with 4,829 additions and 68,524 deletions.
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -102,3 +102,7 @@ typings/

# TernJS port file
.tern-port

# IDE
.vscode/settings.json
.idea/
5 changes: 5 additions & 0 deletions .husky/pre-commit
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
#!/usr/bin/env sh

. "$(dirname -- "$0")/_/husky.sh"

npm test && npm run build && git add dist/*
1 change: 1 addition & 0 deletions .npmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
auto-install-peers = false
106 changes: 51 additions & 55 deletions README-zh-cn.md
Original file line number Diff line number Diff line change
@@ -1,115 +1,111 @@
## article-webpage-to-markdown-action
# Article Web-page to Markdown action

![GitHub](https://img.shields.io/github/license/freeCodeCamp-China/article-webpage-to-markdown-action) ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/freeCodeCamp-China/article-webpage-to-markdown-action) ![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/freeCodeCamp-China/article-webpage-to-markdown-action?include_prereleases&label=release-last)
![GitHub](https://img.shields.io/github/license/freeCodeCamp-China/article-webpage-to-markdown-action)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/freeCodeCamp-China/article-webpage-to-markdown-action)
![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/freeCodeCamp-China/article-webpage-to-markdown-action?include_prereleases&label=release-last)

语言: [English](./README.md) | 简体中文

### 简介
## 简介

根据文章的网页自动生成 Markdown 文件。目前只支持 freeCodeCamp 的 news 站点。
根据文章的网页自动生成 Markdown 文件。

#### 项目结构
```
### 项目结构

```plain
news-translate
| action.yml /** 入口文件 **/
| action.yml // 入口文件
│ package.json
│ README.md
|-.github
│ |-ISSUE_TEMPLATE
│ │ AutoGenerateMarkdown.md /** 自动生成 Markdown 文件的 issue 模板 **/
│ │ AutoGenerateMarkdown.md // 自动生成 Markdown 文件的 issue 模板
│ │
│ |-workflows
│ WebPageToMarkdown.yml /** 用于自动生成 Markdown 文件的 Actions 文件 **/
│ WebPageToMarkdown.yml // 用于自动生成 Markdown 文件的 Actions 文件
|-dist /** 编译后的静态文件夹 **/
|-dist // 编译后的静态文件夹
|
|-node_modules
|-src
|-toMarkdown
| index.js /** 脚本的入口文件 **/
| toMarkdownConstant.js /** 配置文件 **/
| utilities.js /** 函数库文件 **/
|
|-__tests__
utilities.test.js /** 测试文件 **/
| |-index.ts // 脚本的入口文件
| |-toMarkdownConstant.ts // 配置文件
| |-utilities.ts // 函数库文件
|
|-test
|-utilities.test.ts // 测试文件
```
---
<h3>Usage</h3>

在 job 中添加下面的 step.
### 用法

在 GitHub action 配置文件的 `jobs` 字段中添加下面的 step:

```yml
- uses: freeCodeCamp-China/article-webpage-to-markdown-action@v0.1.8
- uses: freeCodeCamp-China/article-webpage-to-markdown-action@v1
with:
newsLink: '${{ github.event.issue.Body }}'
markDownFilePath: './chinese/articles/'
markDownFilePath: './articles/'
githubToken: ${{ github.token }}
```
下面是一个扩展示例,尽可能包含所有选项
下面是一个扩展示例,尽可能包含所有选项
```yml
- uses: freeCodeCamp-China/article-webpage-to-markdown-action@v0.1.8
- uses: freeCodeCamp-China/article-webpage-to-markdown-action@v1
with:
# 一个特定的格式的字符串,该字符串包含一个指向 freeCodeCamp 的News 的链接。
# 格式: "原文网址:[原文标题](https://www.freecodecamp.org/news/xxxxxxx/"
# 一个包含原文 URL 的字符串
newsLink: '${{ github.event.issue.Body }}'
# 需忽略元素的 CSS 选择符
ignoreSelector: '.ad-wrapper'
# 生成 MarkDown 文件的路径
# 相对命令行位置的相对路径
markDownFilePath: './chinese/articles/'
# 相对命令行工作目录的相对路径
markDownFilePath: './articles/'
githubToken: ${{ github.token }}
```
<h4 id="submit-an-issue">通过 GitHub 的 issue 运行脚本</h4>
如果未配置选项 `markDownFilePath`,则默认情况下会在当前路径中生成文件。

**Issues** >> **New issue** >> 填写 issue 的标题和描述 >> **Submit new issue**
### 通过 GitHub 的 issue 运行脚本

#### 描述(Description):
```
- 原文网址:[原文标题](https://www.freeCodeCamp.org/news/路由/)
- MarkDown 文件:https://github.com/freeCodeCamp/news-translation/edit/master/chinese/articles/文章文件名称.md
```
用原文标题替换 `原文标题`,用文章的路由地址替换 `路由` 和 `文章文件名称`。
**Issues** >> **New issue** >> 填写 issue 的标题和描述 >> **Submit new issue**

#### 示例:
如果文章的 URL 是 `https://www.freecodecamp.org/news/Example/`,标题是 `Example Title`。
### 描述

*标题(Title):*
```
[Auto]示例标题
```
*描述(Description):*
```
- 原文网址:[Example Title](https://www.freeCodeCamp.org/news/Example/)
- MarkDown 文件:https://github.com/freeCodeCamp/news-translation/edit/master/chinese/articles/Example.md
```markdown
[原文链接](https://example.com/path/to/your/article/)
```

可以通过检查 **Actions** 的执行结果,以确认脚本是否成功执行。或者在选项 `markDownFilePath` 中设置的位置检查文件是否存在。 如果未配置选项`markDownFilePath`,则默认情况下会在当前路径中生成文件
用原文 URL 替换上文中的 URL,本 action 会在 issue 提交后运行,并将成功或失败消息发到 issue 评论中

如果脚本执行**失败**,您需要确认问题,解决问题,然后根据前面的步骤发布**新 issue**。 [*常见错误消息*](#CommonErrorMessages) 和 *Actions 的日志* 将为您提供一些可靠的提示。
如果脚本执行**失败**,您需要确认问题,解决问题,然后根据前面的步骤发布**新 issue**。 [_常见错误消息_](#常见错误消息) 和 _Actions 的日志_ 将为您提供一些可靠的提示。

<h3 id="CommonErrorMessages">常见错误消息</h3>
### 常见错误消息

- **No parameters were found. Please confirm that the description of the issue has been entered.**
issue 的描述为空,请根据模板填写内容。
- **The route to the article is not matched. Please confirm that the URL is correct.**
在 issue 的描述中,只需要替换 `原文标题`, `路由` 和 `文章文件名称` 即可,并且请保留其他字符。
- **There is one file with the same name exists.Please check if the article has been added.**
在 `./chinese/articles` 文件夹下有一个同名文件。
在 `markDownFilePath` 文件夹下有一个同名文件。
- **The DOM of the website has been modified, or there is a problem with loading, please confirm.**
网站的 DOM 结构可能更改,并且脚本需要修改。

---

## 高级用例

### 客户端渲染

本 action 只能处理静态或服务端渲染的网页,对于客户端渲染,我们推荐 https://github.com/TechQuery/Web-fetch#in-github-actions .

---

## 贡献者指南

请转到[贡献者指南](CONTRIBUTING.md)。

---

### 许可证
## 许可证

- 程序遵循 [BSD-3-Clause](LICENSE) 许可证。
程序遵循 [BSD-3-Clause](LICENSE) 许可证。
105 changes: 50 additions & 55 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,116 +1,111 @@
# article-webpage-to-markdown-action
# Article Web-page to Markdown action

![GitHub](https://img.shields.io/github/license/freeCodeCamp-China/article-webpage-to-markdown-action) ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/freeCodeCamp-China/article-webpage-to-markdown-action) ![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/freeCodeCamp-China/article-webpage-to-markdown-action?include_prereleases&label=release-last)
![GitHub](https://img.shields.io/github/license/freeCodeCamp-China/article-webpage-to-markdown-action)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/freeCodeCamp-China/article-webpage-to-markdown-action)
![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/freeCodeCamp-China/article-webpage-to-markdown-action?include_prereleases&label=release-last)

Language: English | [简体中文](./README-zh-cn.md)

### Introduction
## Introduction

Automatically generate Markdown files based on the webpages of articles. Currently supports freecodecamp's news site.
Automatically generate Markdown files based on the Web-pages of articles.

### Project structure

#### Project structure

```
```plain
news-translate
| action.yml /** Entry file **/
| action.yml // Entry file
│ package.json
│ README.md
|-.github
│ |-ISSUE_TEMPLATE
│ │ AutoGenerateMarkdown.md /** Automatically generate Markdown issue template **/
│ │ AutoGenerateMarkdown.md // Automatically generate Markdown issue template
│ │
│ |-workflows
│ WebPageToMarkdown.yml /** Actions file for automatically generating Markdown files **/
│ WebPageToMarkdown.yml // Actions file for automatically generating Markdown files
|-dist /** Compiled static folder **/
|-dist // Compiled static folder
|-node_modules
|-src
|-toMarkdown
| index.js /** Entry file of the script **/
| toMarkdownConstant.js /** Configuration file **/
| utilities.js /** Function library file **/
|
|-__tests__
utilities.test.js /** test file **/
| |-index.ts // Entry file of the script
| |-toMarkdownConstant.ts // Configuration file
| |-utilities.ts // Function library file
|
|-test
|-utilities.test.ts // test file
```

---

<h3 id="Usage">Usage</h3>
### Usage

Add the following step your job.
Add the following step in the `jobs` field of your GitHub action configuration:

```yml
- uses: freeCodeCamp-China/article-webpage-to-markdown-action@v0.1.8
- uses: freeCodeCamp-China/article-webpage-to-markdown-action@v1
with:
newsLink: '${{ github.event.issue.Body }}'
markDownFilePath: './chinese/articles/'
markDownFilePath: './articles/'
githubToken: ${{ github.token }}
```
The following is an extended example with all possible options available for this Action.
The following is an extended example with all possible options available for this Action:
```yml
- uses: freeCodeCamp-China/article-webpage-to-markdown-action@v0.1.8
- uses: freeCodeCamp-China/article-webpage-to-markdown-action@v1
with:
# A string in a specific format that contains a link to freeCodeCamp News
# format: "原文网址:[原文标题](https://www.freecodecamp.org/news/xxxxxxx/"
# A string contains an Original Article URL
newsLink: '${{ github.event.issue.Body }}'
# CSS selector of elements which should be ignored
ignoreSelector: '.ad-wrapper'
# Path of the generated MarkDown file
# Relative path relative to the root folder
markDownFilePath: './chinese/articles/'
# Relative path relative to current working directory
markDownFilePath: './articles/'
githubToken: ${{ github.token }}
```
<h4 id="submit-an-issue">Run the script by the issue of GitHub</h4>
If you do not configure the option `markDownFilePath`, the file is generated in the current path by default.

**Issues** >> **New issue** >> Fill in the title and description of the issue >> **Submit new issue**
### Run the script by the issue of GitHub

#### Description:
```
- 原文网址:[原文标题](https://www.freeCodeCamp.org/news/路由/)
- MarkDown 文件:https://github.com/freeCodeCamp/news-translation/edit/master/chinese/articles/文章文件名称.md
```
Replace `原文标题` with the original title. And replace `路由` and `文章文件名称` with the route of the article.
**Issues** >> **New issue** >> Fill in the title and description of the issue >> **Submit new issue**

#### e.g.
If the URL of an article is `https://www.freecodecamp.org/news/Example/`, and its title is `Example Title`.
### Description

*Description:*
```markdown
[Original article](https://example.com/path/to/your/article/)
```
- 原文网址:[Example Title](https://www.freecodecamp.org/news/Example/)
- MarkDown 文件:https://github.com/freeCodeCamp/news-translation/edit/master/chinese/articles/Example.md
```
If you want to confirm whether the script is executed successfully, you can check the execution result of **Actions**, or check the existence of the file at the location you set in the option `markDownFilePath`. If you do not configure the option `markDownFilePath`, the file is generated in the current path by default.

If the script execution **fails**, you need to confirm the problem, solve them, and post a **new issue** according to the previous steps. In the **Action log**, The [*Common Error Messages*](#CommonErrorMessages) will give you some reliable tips.
Replace the Link Value with the URL of an Original article, after the issue submitted, the action will run, and a success or failed message will be commented to the issue in the end.

---
If the script execution **fails**, you need to confirm the problem, solve them, and post a **new issue** according to the previous steps. In the **Action log**, The [_Common Error Messages_](#Common-Error-Messages) will give you some reliable tips.

<h3 id="CommonErrorMessages">Common Error Messages</h3>
### Common Error Messages

- **No parameters were found. Please confirm that the description of the issue has been entered.**
The description of the issue is empty, please fill in the content according to the template.
- **The route to the article is not matched. Please confirm that the URL is correct.**
In the description of the issue, you only need to replace `原文标题`, `路由` and `文章文件名称`. And please keep other characters.
- **There is one file with the same name exists.Please check if the article has been added.**
There is a file with the same name under the folder `./chinese/articles`.
- **There is one file with the same name exists. Please check if the article has been added.**
There is a file with the same name under the folder `markDownFilePath`.
- **The DOM of the website has been modified, or there is a problem with loading, please confirm.**
The DOM structure of the website may be changed and the script needs to be modified.

---

## Advanced cases

### Client-side rendering

This action can only handle Static or Server-side rendered pages, for Client-side rendered pages, we recommend https://github.com/TechQuery/Web-fetch#in-github-actions .

---

## Contributing guide

Please go to the [contributing guide](CONTRIBUTING.md).

---

### License
## License

- The computer software is licensed under the [BSD-3-Clause](LICENSE) license.
The computer software is licensed under the [BSD-3-Clause](LICENSE) license.
20 changes: 11 additions & 9 deletions action.yml
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
name: "article-webpage-to-markdown-action"
description: "Automatically generate Markdown files based on the webpages of articles. Currently supports freecodecamp's news site."
author: "freeCodeCamp-China"
name: 'article-webpage-to-markdown-action'
description: "Automatically generate Markdown files based on the webpages of articles. Currently supports freeCodeCamp's news site."
author: 'freeCodeCamp-China'
inputs:
newsLink:
description: "A string in a specific format that contains a link to a article."
description: 'A string in a specific format that contains a link to a article.'
required: true
ignoreSelector:
description: 'CSS selector of elements which should be ignored'
markDownFilePath:
description: "Path of the generated MarkDown file and relative path relative to the root folder."
description: 'Path of the generated MarkDown file and relative path relative to the root folder.'
required: false
default: "./"
default: './'
githubToken:
description: " GitHub write and read token,auto create,no need to set"
description: ' GitHub write and read token,auto create,no need to set'
default: ''

runs:
using: "node12"
main: "dist/index.js"
using: 'node20'
main: 'dist/index.js'
Loading

0 comments on commit 47304a8

Please sign in to comment.