Skip to content

Commit e59a062

Browse files
haunerhauner
authored
Merge pull request #2 from hauner/clean
rebuild simpler & better layout from scratch
2 parents bfc017c + c271a44 commit e59a062

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

67 files changed

+4921
-2218
lines changed

‎.gitlab-ci.yml

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
image: node:10.14.2-stretch
2+
stages: [setup, verify, deploy]
3+
install:
4+
stage: setup
5+
cache:
6+
paths:
7+
- .cache/npm
8+
script:
9+
- &npm_install
10+
npm install --quiet --no-progress --cache=.cache/npm
11+
lint:
12+
stage: verify
13+
cache: &pull_cache
14+
policy: pull
15+
paths:
16+
- .cache/npm
17+
script:
18+
- *npm_install
19+
- node_modules/.bin/gulp lint
20+
bundle-stable:
21+
stage: deploy
22+
only:
23+
- master@antora/antora-ui-default
24+
cache: *pull_cache
25+
script:
26+
- *npm_install
27+
- node_modules/.bin/gulp bundle
28+
artifacts:
29+
paths:
30+
- build/ui-bundle.zip
31+
bundle-dev:
32+
stage: deploy
33+
except:
34+
- master
35+
cache: *pull_cache
36+
script:
37+
- *npm_install
38+
- node_modules/.bin/gulp bundle
39+
artifacts:
40+
expire_in: 1 day # unless marked as keep from job page
41+
paths:
42+
- build/ui-bundle.zip
43+
pages:
44+
stage: deploy
45+
only:
46+
- master@antora/antora-ui-default
47+
cache: *pull_cache
48+
script:
49+
- *npm_install
50+
- node_modules/.bin/gulp preview:build
51+
# FIXME figure out a way to avoid copying these files to preview site
52+
- rm -rf public/_/{helpers,layouts,partials}
53+
artifacts:
54+
paths:
55+
- public

‎.stylelintrc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,11 @@
33
"rules": {
44
"comment-empty-line-before": null,
55
"no-descending-specificity": null,
6+
"at-rule-no-unknown": [
7+
true,
8+
{
9+
"ignoreAtRules": ["tailwind", "responsive"]
10+
}
11+
]
612
}
713
}

‎docs/antora.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
name: antora-ui-default
2+
title: Antora Default UI
3+
version: master
4+
nav:
5+
- modules/ROOT/nav.adoc

‎docs/modules/ROOT/nav.adoc

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
* xref:prerequisites.adoc[UI Development Prerequisites]
2+
* xref:set-up-project.adoc[Set up a UI Project]
3+
* xref:build-preview-ui.adoc[Build and Preview the UI]
4+
* xref:development-workflow.adoc[UI Development Workflow]
5+
* xref:templates.adoc[Work with the Handlebars Templates]
6+
* xref:stylesheets.adoc[Work with the CSS Stylesheets]
7+
** xref:add-fonts.adoc[Add Fonts]
8+
* xref:style-guide.adoc[UI Element Styles]
9+
** xref:inline-text-styles.adoc[Inline Text]
10+
** xref:admonition-styles.adoc[Admonitions]
11+
** xref:list-styles.adoc[Lists]
12+
** xref:sidebar-styles.adoc[Sidebars]
13+
** xref:ui-macro-styles.adoc[UI Macros]

‎docs/modules/ROOT/pages/add-fonts.adoc

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
= Add Fonts
2+
3+
This page explains how to add new fonts to your UI.
4+
These instructions assume you've forked the default UI and are able to customize it.
5+
6+
There are three steps involved:
7+
8+
. Add the font to your UI project
9+
. Add a font-face declaration to your stylesheet
10+
. Use the new font in your stylesheet
11+
12+
How you reference the font file in the font-face declaration depends on how you decide to manage it.
13+
You can manage the font with npm or download it manually and add it directly to your UI project.
14+
The following sections describe each approach in turn.
15+
16+
== npm managed
17+
18+
You can use npm (or Yarn) to manage the font.
19+
This approach saves you from having to store the font file directly in your UI project.
20+
Here are the steps involved.
21+
22+
. Use npm (or Yarn) to install the font files from a package (e.g., https://www.npmjs.com/package/typeface-open-sans[typeface-open-sans])
23+
24+
$ npm install --save typeface-open-sans
25+
26+
. In [.path]_src/css_, add a corresponding CSS file (e.g., [.path]_typeface-open-sans.css_)
27+
. In that file, declare the font face:
28+
+
29+
[source,css]
30+
----
31+
@font-face {
32+
font-family: "Open Sans";
33+
font-style: normal;
34+
font-weight: 400;
35+
src:
36+
local("Open Sans"),
37+
local("Open Sans-Regular"),
38+
url(~typeface-open-sans/files/open-sans-latin-400.woff) format("woff")
39+
}
40+
----
41+
+
42+
The Gulp build recognizes the `~` URL prefix and copies the font from the npm package to the build folder (and hence bundle).
43+
+
44+
You must define one @font-face for each font weight and style combination (e.g., `font-weight: 500` + `font-style: italic`) from the font that you want to use in your stylesheet.
45+
46+
. Import the typeface CSS file you just created into the main stylesheet, [.path]_src/css/site.css_ (adjacent to the other typeface imports):
47+
+
48+
[source,css]
49+
----
50+
@import "typeface-open-sans.css";
51+
----
52+
53+
. Repeat the previous steps for each font style and weight you want to use from that package.
54+
. Change the CSS to use your newly imported font:
55+
+
56+
[source,css]
57+
----
58+
html {
59+
font-family: "Open Sans", sans;
60+
}
61+
----
62+
+
63+
TIP: If you're building on the default UI, you may instead want to define or update the font family using a variable defined in [.path]_src/css/vars.css_.
64+
65+
. Test the new font by previewing your UI:
66+
67+
$ gulp preview
68+
69+
If you see the new font, you've now successfully added it to your UI.
70+
If you aren't sure, look for the https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Edit_fonts[All fonts on page] section in your browser's developer tools to see whether the font was loaded.
71+
72+
== Manual
73+
74+
A simpler approach to adding fonts is to store them directly in your project.
75+
Here are the steps involved.
76+
77+
. Download the font files and add them to the [.path]_src/font_ folder.
78+
Create this folder if it does not exist.
79+
. In [.path]_src/css_, add a corresponding CSS file (e.g., [.path]_typeface-open-sans.css_)
80+
. In that file, declare the font face:
81+
+
82+
[source,css]
83+
----
84+
@font-face {
85+
font-family: "Open Sans";
86+
font-style: normal;
87+
font-weight: 400;
88+
src:
89+
local("Open Sans"),
90+
local("Open Sans-Regular"),
91+
url(../font/open-sans-latin-400.woff) format("woff")
92+
}
93+
----
94+
+
95+
Note that the path is a relative path starting from the [.path]_src/css_ folder to the [.path]_src/font_ folder.
96+
+
97+
You must define one @font-face for each font weight and style combination (e.g., `font-weight: 500` + `font-style: italic`) from the font that you want to use in your stylesheet.
98+
99+
. Import the typeface CSS file you just created into the main stylesheet, [.path]_src/css/site.css_ (adjacent to the other typeface imports):
100+
+
101+
[source,css]
102+
----
103+
@import "typeface-open-sans.css";
104+
----
105+
106+
. Repeat the previous steps for each font style and weight you want to use.
107+
. Change the CSS to use your newly imported font:
108+
+
109+
[source,css]
110+
----
111+
html {
112+
font-family: "Open Sans", sans;
113+
}
114+
----
115+
+
116+
TIP: If you're building on the default UI, you may instead want to define or update the font family using a variable defined in [.path]_src/css/vars.css_.
117+
118+
. Test the new font by previewing your UI:
119+
120+
$ gulp preview
121+
122+
If you see the new font, you've now successfully added it to your UI.
123+
If you aren't sure, look for the https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Edit_fonts[All fonts on page] section in your browser's developer tools to see whether the font was loaded.

‎docs/modules/ROOT/pages/admonition-styles.adoc

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
= Admonition Styles
2+
3+
An xref:antora:asciidoc:admonitions.adoc[admonition], also known as a notice, helps draw attention to content with a special label or icon.
4+
5+
== Admonition blocks
6+
7+
An admonition block is a table.
8+
The table title element is specified by the block class: tip, note, important, warning, or caution.
9+
Here's an AsciiDoc source example that produces an admonition with the table title warning:
10+
11+
[source,asciidoc]
12+
----
13+
WARNING: Watch out!
14+
----
15+
16+
If font-based icons are enabled (`icons=font`), the table title text is replaced by the associated icon.
17+
18+
[source,html]
19+
----
20+
<div class="admonitionblock warning">
21+
<table>
22+
<tr>
23+
<td class="icon">
24+
<i class="fa icon-warning" title="Warning"></i>
25+
</td>
26+
<td class="content">
27+
<div class="paragraph">
28+
<p>Watch out!</p>
29+
</div>
30+
</td>
31+
</tr>
32+
</table>
33+
</div>
34+
----
35+
36+
Here's how it might appear when the title is displayed as text:
37+
38+
WARNING: Watch out!

‎docs/modules/ROOT/pages/build-preview-ui.adoc

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
= Build a UI Project for Local Preview
2+
// Settings:
3+
:idprefix:
4+
:idseparator: -
5+
:experimental:
6+
7+
== Build Preview Site
8+
9+
Once you've modified the site UI, the first thing you'll want to do is check out how it looks.
10+
That's what the files in the [.path]_preview-src/_ folder are for.
11+
This folder contains HTML file fragments that provide a representative sample of content from the site.
12+
The preview saves you from having to generate the whole site just to test the UI.
13+
These files should give you an idea of how the UI will look when applied to the actual site.
14+
15+
The pages in the preview site are assembled using the Handlebars templates and link to the pre-compiled asset files (emulating the behavior of the site generator).
16+
Thus, to look at them, you need to run them through the UI build.
17+
18+
There are two preview modes available.
19+
You can run the build once and examine the result or you can run the build continuously so you can see changes as you make them.
20+
The next two sections explain how to use these modes.
21+
22+
=== Build Once
23+
24+
To build the UI once for preview, then stop, execute the following command:
25+
26+
$ gulp preview:build
27+
28+
This task pre-compiles the UI files into the [.path]_public_ directory.
29+
To view the preview pages, navigate to the HTML pages in the [.path]_public_ directory using your browser (e.g., [.path]_public/index.html_).
30+
31+
=== Build Continuously
32+
33+
To avoid the need to run the `preview:build` task over and over while developing, you can use the `preview` command instead to have it run continuously.
34+
This task also launches a local HTTP server so updates get synchronized with the browser (i.e., "`live reload`").
35+
36+
To launch the preview server, execute the following command:
37+
38+
$ gulp preview
39+
40+
You'll see a URL listed in the output of this command:
41+
42+
....
43+
[12:59:28] Starting 'preview:serve'...
44+
[12:59:28] Starting server...
45+
[12:59:28] Server started http://localhost:5252
46+
[12:59:28] Running server
47+
....
48+
49+
Navigate to the URL to view the preview site.
50+
While this command is running, any changes you make to the source files will be instantly reflected in the browser.
51+
This works by monitoring the project for changes, running the `preview:build` task if a change is detected, and sending the updates to the browser.
52+
53+
Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
54+
55+
== Package for Previewing
56+
57+
If you need to bundle the UI in order to preview the UI on the real site in local development, run the following command:
58+
59+
$ gulp bundle
60+
61+
The `bundle` command also invokes the `lint` command to check that the CSS and JavaScript follow the coding standards.
62+
63+
The UI bundle will be available at [.path]_build/ui-bundle.zip_.
64+
You can then point Antora at this bundle using the `--ui-bundle-url` command-line option.
65+
66+
If you have the preview running, and you want to bundle without causing the preview to be clobbered, use:
67+
68+
$ gulp bundle:pack
69+
70+
The UI bundle will again be available at [.path]_build/ui-bundle.zip_.

‎docs/modules/ROOT/pages/development-workflow.adoc

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
= UI Development Workflow
2+
// Settings:
3+
:idprefix:
4+
:idseparator: -
5+
6+
// This section provides information about some of the UI files you'll be modifying and how to prepare and submit those changes.
7+
8+
All changes pushed to a UI project's master branch can trigger a new release (not described here).
9+
Therefore, you want to make your changes to a development branch and submit it as a pull request (PR) to be approved.
10+
(Even better would be to issue the PR from a fork).
11+
Only when the PR is approved and merged will the new release be triggered.
12+
13+
== git steps
14+
15+
Use the following command to create a local development branch named `name-me`:
16+
17+
$ git checkout -b name-me -t origin/master
18+
19+
You'll then apply your changes to the UI files.
20+
Once you're done making changes, commit those changes to the local branch:
21+
22+
$ git commit -a -m "describe your change"
23+
24+
Then, push your branch to the remote repository:
25+
26+
$ git push origin name-me
27+
28+
Finally, navigate to your UI project in your browser and create a new pull request from this branch.
29+
30+
The maintainer of the UI should review the changes.
31+
If the changes are acceptable, the maintainer will merge the pull request.
32+
As soon as the pull request is merged into master, an automated process will take over to publish a new release for the site generator to use.
33+
34+
Now that you've got the process down, let's review some of the files you'll be working with in more detail.

0 commit comments

Comments
 (0)