git724/forgejo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 8

Add markdownlint (#20512)

Browse source 
Add `markdownlint` linter and fix issues. Config is based on the one
from electron's repo with a few rules relaxed.
This commit is contained in:
silverwind 2022-07-28 03:22:47 +02:00 • committed by GitHub
parent 6554d5197f
commit ae52df6a64
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
68 changed files with 1339 additions and 823 deletions
Download patch file Download diff file Expand all files Collapse all files

17
docs/content/doc/developers/guidelines-frontend.md
View file

@ -26,6 +26,7 @@ Gitea uses [Less CSS](https://lesscss.org), [Fomantic-UI](https://fomantic-ui.co
The HTML pages are rendered by [Go HTML Template](https://pkg.go.dev/html/template).
The source files can be found in the following directories:
* **Less styles:** `web_src/less/`
* **JavaScript files:** `web_src/js/`
* **Vue components:** `web_src/js/components/`
@ -41,36 +42,37 @@ We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/h
2. HTML ids and classes should use kebab-case.
3. HTML ids and classes used in JavaScript should be unique for the whole project, and should contain 2-3 feature related keywords. We recommend to use the `js-` prefix for classes that are only used in JavaScript.
4. jQuery events across different features could use their own namespaces if there are potential conflicts.
5. CSS styling for classes provided by frameworks should not be overwritten. Always use new class-names with 2-3 feature related keywords to overwrite framework styles.
5. CSS styling for classes provided by frameworks should not be overwritten. Always use new class-names with 2-3 feature related keywords to overwrite framework styles.
6. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`
7. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue2 (or Vue3 in future).
### Framework Usage
Mixing different frameworks together is discouraged, it makes the code difficult to be maintained.
A JavaScript module should follow one major framework and follow the framework's best practice.
Recommended implementations:
* Vue + Vanilla JS
* Fomantic-UI (jQuery)
* Vanilla JS
Discouraged implementations:
* Vue + Fomantic-UI (jQuery)
* jQuery + Vanilla JS
To make UI consistent, Vue components can use Fomantic-UI CSS classes.
Although mixing different frameworks is discouraged,
it should also work if the mixing is necessary and the code is well-designed and maintainable.
Although mixing different frameworks is discouraged,
it should also work if the mixing is necessary and the code is well-designed and maintainable.
### `async` Functions
Only mark a function as `async` if and only if there are `await` calls
Only mark a function as `async` if and only if there are `await` calls
or `Promise` returns inside the function.
It's not recommended to use `async` event listeners, which may lead to problems.
The reason is that the code after await is executed outside the event dispatch.
The reason is that the code after await is executed outside the event dispatch.
Reference: https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
If we want to call an `async` function in a non-async context,
@ -88,10 +90,9 @@ However, there are still some special cases, so the current guideline is:
* `$.data()` can be used to bind some non-string data to elements in rare cases, but it is highly discouraged.
* For new code:
* `node.dataset` should not be used, use `node.getAttribute` instead.
* `node.dataset` should not be used, use `node.getAttribute` instead.
* never bind any user data to a DOM node, use a suitable design pattern to describe the relation between node and data.
### Legacy Code
A lot of legacy code already existed before this document's written. It's recommended to refactor legacy code to follow the guidelines.