Skip to content

Commit d906499

Browse files
ktquezktquez
authored
Merge pull request #34 from vue-a11y/docs/posts-guide
Posts guide
2 parents ca5efea + bde5673 commit d906499

File tree

8 files changed

+442
-7
lines changed

8 files changed

+442
-7
lines changed

‎src/.vuepress/config/head.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ module.exports = [
6262
['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com/' }],
6363
['link', { rel: 'preconnect', href: 'https://c.disquscdn.com/' }],
6464
['link', { rel: 'preconnect', href: 'https://disqus.com/' }],
65-
['link', { rel: 'preconnect', href: 'http://vue-a11y-test.disqus.com' }],
65+
['link', { rel: 'preconnect', href: 'https://vue-a11y.disqus.com' }],
6666
['link', { rel: 'preconnect', href: 'https://c.disquscdn.com/next/' }],
6767
['link', { rel: 'preconnect', href: 'https://links.services.disqus.com/api/' }],
6868
['link', { rel: 'preconnect', href: 'https://www.google-analytics.com/' }],

‎src/.vuepress/theme/components/PageEdit.vue

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
class="mb-4 border-b-2 border-accent-primary"
1111
/>
1212
<div
13-
v-if="$themeConfig.lastUpdated"
13+
v-if="$themeConfig.lastUpdated && $page.lastUpdated"
1414
class="last-update"
1515
>
1616
<span class="font-bold">
@@ -35,7 +35,7 @@ export default {
3535
3636
setup (_, { root }) {
3737
const editLink = computed(() => `https://github.com/${root.$themeConfig.repo}/edit/${root.$themeConfig.docsBranch || 'master'}/${root.$themeConfig.docsDir || 'docs'}/${root.$page.relativePath}`)
38-
const datetime = new Date(root.$page.lastUpdated).toISOString()
38+
const datetime = root.$page.lastUpdated && new Date(root.$page.lastUpdated).toISOString()
3939
4040
return {
4141
datetime,

‎src/.vuepress/theme/layouts/Post.vue

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ export default {
162162
}))
163163
164164
const disqus = {
165-
shortname: 'vue-a11y-test',
165+
shortname: 'vue-a11y',
166166
lazyConfig: {
167167
root: null,
168168
rootMargin: '1000px',

‎src/.vuepress/theme/styles/_custom-blocks.scss

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
&:before {
2121
@apply absolute text-accent-primary border-none;
2222
content: '“';
23-
top: 20px;
23+
top: -67px;
2424
left: -20px;
2525
font-size: 150px;
2626
font-family: "Helvetica";

‎src/project/how-to-contribute.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,6 @@ description: Find out how to contribute to Vue Accessibility project
77

88
First of all, happy that you are here on this page and thinking about contributing to the project.
99

10-
**The Vue.js community thanks you.**
11-
1210
## Development
1311

1412
To contribute to the development of the site, you can initially open an issue on Github and report an error or propose a new feature.
@@ -35,6 +33,10 @@ We also have an [issue](https://github.com/vue-a11y/vue-a11y.com/issues/14) with
3533

3634
Our intention is to reward the creator for each content published on the site, we will soon achieve this feat.
3735

36+
::: alert warning
37+
We created a guide with tips for creating posts, recipes, or tips. [Posts guide](/project/posts-guide.html#posts-guide)
38+
:::
39+
3840
## Answering questions
3941

4042
In our [GitHub Problem Tracker](https://github.com/vue-a11y/vue-a11y.com/issues), we are open to answering questions from people of all levels of knowledge.

‎src/project/posts-guide.md

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
---
2+
description: Guidelines for creating content for Vue.js A11y (posts, recipes and tips).
3+
---
4+
# Posts guide
5+
6+
## How to begin
7+
8+
First of all, do a brief search to see if your post idea does not yet exist on the site.
9+
10+
If you are looking for ideas, we have an [issue](https://github.com/vue-a11y/vue-a11y.com/issues/14) with several post ideas, feel free to reserve a subject.
11+
12+
After checking, reserve your post by opening an issue using some of our templates:
13+
14+
- [New Post/Article](https://github.com/vue-a11y/vue-a11y.com/issues/new?labels=Post&template=new-post.md&title=Post%2FArticle%3A+%5BYour+title%5D)
15+
- [New Widget (Recipe)](https://github.com/vue-a11y/vue-a11y.com/issues/new?labels=Recipe,Widget&template=new-widget.md&title=Recipe%28widget%29%3A+%5BYour+title%5D)
16+
- [New Tip (Recipe)](https://github.com/vue-a11y/vue-a11y.com/issues/new?labels=Recipe,Tip&template=new-tip.md&title=Recipe%28Tip%29%3A+%5BYour+title%5D)
17+
18+
After booking a subject, fork the repository, follow the steps in our [README](https://github.com/vue-a11y/vue-a11y.com/blob/master/README.md) for installation.
19+
20+
Create a markdown file in the specific post type directory and in the language in which the post will be written.
21+
22+
For example in the English language:
23+
24+
- `src/posts`: For blog posts;
25+
- `src/recipes/widgets`: For posting widgets;
26+
- `src/recipes/tips`: For quick tip posts;
27+
28+
::: alert warning
29+
Follow the structure `2020-05-12-my-post.md`
30+
:::
31+
32+
After completing, create a PR and request review from members for the latest adjustments and merge your post.
33+
34+
## Frontmatter
35+
36+
### Blog posts
37+
38+
::: headerCode
39+
2020-05-12-my-post.md
40+
:::
41+
```yaml
42+
---
43+
title: Post title # (Required) - between 50-65 characters
44+
description: Description of the post # (Required) - up to 155 characters
45+
summary: Summary of the post or tl;dr # (Optional)
46+
categories: Array of categories that match the post # (Required)
47+
tag: Array of tags that match the post # (Optional)
48+
author: author's nickname # (Optional)
49+
date: YYYY/MM/DD HH:ii:ss # (Required)
50+
---
51+
```
52+
53+
::: alert warning
54+
Available categories: `[news, aria, wcag, tools, packages, spa, html]`.
55+
:::
56+
57+
::: alert warning
58+
The tags have no limitations, you can create as many tags as you want `[screen-reader, form, ...]`.
59+
:::
60+
61+
::: alert tip
62+
Add your author information `src/config/authors.json`, soon we will have a page dedicated to the authors of the site.
63+
:::
64+
65+
## Best pratices
66+
67+
- Use a correct hierarchy of headings;
68+
- Add the lang to the code blocks (highlight code);
69+
- Alternative text in images;
70+
- Write simply and understandably;
71+
- [Avoid wall of text](https://axesslab.com/accessibility-according-to-pwd/#wall-of-text);
72+
- Use lazy-load for iframes (IntersectObserver Component)
73+
74+
## Using custom blocks
75+
76+
### Figure + Blockquote + Figcaption
77+
78+
::: headerCode
79+
:::
80+
```
81+
:::: fig bq
82+
::: bq
83+
VuePress is composed of two parts: a minimalistic static site generator with a Vue-powered theming system and Plugin API, and a default theme optimized for writing technical documentation.
84+
:::
85+
::: figcap
86+
[Vuepress documentation](https://vuepress.vuejs.org/)
87+
:::
88+
::::
89+
```
90+
91+
:::: fig bq
92+
::: bq
93+
VuePress is composed of two parts: a minimalistic static site generator with a Vue-powered theming system and Plugin API, and a default theme optimized for writing technical documentation.
94+
:::
95+
::: figcap
96+
[Vuepress documentation](https://vuepress.vuejs.org/)
97+
:::
98+
::::
99+
100+
### Tip, Note, Warning, Danger
101+
102+
::: headerCode
103+
:::
104+
```
105+
::: alert tip
106+
This is a tip
107+
:::
108+
109+
::: alert note
110+
This is a note
111+
:::
112+
113+
::: alert warning
114+
This is a warning
115+
:::
116+
117+
::: alert danger
118+
This is a danger
119+
:::
120+
```
121+
122+
::: alert tip
123+
This is a tip
124+
:::
125+
126+
::: alert note
127+
This is a note
128+
:::
129+
130+
::: alert warning
131+
This is a warning
132+
:::
133+
134+
::: alert danger
135+
This is a danger
136+
:::
137+
138+
### Figure + HeaderCode + Code block + Figcaption
139+
140+
```
141+
:::: fig code
142+
::: headerCode
143+
main.js
144+
:::
145+
``js
146+
import Vue from 'vue'
147+
import VueAnnouncer from '@vue-a11y/announcer'
148+
149+
Vue.use(VueAnnouncer)
150+
``
151+
::: figcap
152+
Basic usage of Vue announcer
153+
:::
154+
::::
155+
```
156+
157+
:::: fig code
158+
::: headerCode
159+
main.js
160+
:::
161+
```js
162+
import Vue from 'vue'
163+
import VueAnnouncer from '@vue-a11y/announcer'
164+
165+
Vue.use(VueAnnouncer)
166+
```
167+
::: figcap
168+
Basic usage of Vue announcer
169+
:::
170+
::::
171+
172+
### headerCode + Code block
173+
174+
```
175+
::: headerCode
176+
main.js
177+
:::
178+
``js
179+
import Vue from 'vue'
180+
import VueAnnouncer from '@vue-a11y/announcer'
181+
182+
Vue.use(VueAnnouncer)
183+
``
184+
```
185+
186+
::: headerCode
187+
main.js
188+
:::
189+
```js
190+
import Vue from 'vue'
191+
import VueAnnouncer from '@vue-a11y/announcer'
192+
193+
Vue.use(VueAnnouncer)
194+
```
195+
196+
## Vue in markdown
197+
198+
### IntersectionObserver component
199+
200+
Use this component for lazy-load of iframes, images, among other media.
201+
202+
```vue
203+
<intersection-observer>
204+
<template v-slot="data">
205+
<iframe
206+
v-if="data.show"
207+
src="https://caniuse.bitsofco.de/embed/index.html?feat=hidden&periods=future_1,current,past_1,past_2"
208+
height="420"
209+
allowfullscreen="true"
210+
style="width: 100%">
211+
</iframe>
212+
</template>
213+
</intersection-observer>
214+
```

‎src/pt/projeto/como-contribuir.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@ Nós também temos uma [issue](https://github.com/vue-a11y/vue-a11y.com/issues/1
3333

3434
Nossa intenção é recompensar o criador por cada conteúdo publicado no site, em breve iremos conseguir esse feito.
3535

36+
::: alert warning
37+
Criamos um guia com dicas para criar postagens, receitas ou dicas. [Guia de postagens](/pt/projeto/guia.html#posts-guide).
38+
:::
39+
3640
## Respondendo perguntas
3741

3842
Em nosso [Rastreador de problemas do GitHub](https://github.com/vue-a11y/vue-a11y.com/issues) estamos abertos a responder perguntas de pessoas de todos os níveis de conhecimento.

0 commit comments

Comments
 (0)