Skip to content

Commit b9acd48

Browse files
stefano-ottolenghistefano-ottolenghi
authored
Initial commit
0 parents  commit b9acd48

16 files changed

+5805
-0
lines changed

‎.gitignore

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
*.iml
2+
*.ipr
3+
*.iws
4+
*.sw?
5+
*~
6+
.DS_Store
7+
.cache
8+
.cache-main
9+
.cache-main
10+
.cache-main
11+
.cache-tests
12+
.cache-tests
13+
.cache-tests
14+
.classpath
15+
.externalToolBuilders/
16+
.factorypath
17+
.gradle
18+
.gradletasknamecache
19+
.idea
20+
.java-version
21+
.mailmap
22+
.project
23+
.scala_dependencies
24+
.settings
25+
.shell_history
26+
Thumbs.db
27+
\#*
28+
bin/teamcity/
29+
build/
30+
devenv.local
31+
shared/
32+
src/main/_common-and-old/
33+
tags
34+
target/
35+
36+
# node modules
37+
node_modules/
38+
.env

‎README.adoc

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
= Documentation Template
2+
3+
This repo contains the files that you need to start a new Neo4j documentation project.
4+
5+
== Prereqs
6+
7+
- link:https://nodejs.org/en/download/[Node.js]
8+
- npm
9+
10+
== Installation
11+
12+
To install the required packages:
13+
14+
----
15+
npm i
16+
----
17+
18+
== Generating HTML output
19+
20+
To convert asciidoc source to HTML:
21+
22+
----
23+
npm run build
24+
----
25+
26+
== Viewing HTML output
27+
28+
To view the built site, launch a local server:
29+
30+
1. `npm start`
31+
2. In a browser tab, go to `localhost:8000`
32+
33+
== Live preview
34+
35+
When you run `npm start`, the project is monitored for updates to asciidoc files.
36+
37+
If a change to an asciidoc file is detected the site is automatically rebuilt.
38+
39+
== Generating asciidoc source files
40+
41+
If you are creating new documentation from scratch, creating all the asciidoc files can be time-consuming.
42+
This repo contains a script that you can use to save time by generating skeleton asciidoc files from your navigation.
43+
44+
To use the script, first create your navigation file, or files if your doc set has more than one component. To use the script, all navigation files should have the filename `content-nav.adoc`.
45+
Then, to create the asciidoc source files, run `npm run adoc-gen`.
46+
47+
For every file that is included as a list item entry in a `content-nav.adoc` file, an asciidoc file is created in the location specified.
48+
For example, if _modules/ROOT/content-nav.adoc_ includes `+++* xref:installation/introduction.adoc[]+++`, a file is created at _modules/ROOT/pages/installation/introduction.adoc_.
49+
50+
The file contents consist of a comment to indicate that the file was generated by the script, and a top level title element.
51+
If title text is specified in the entry in the navigation file, that value will be used for the title in the generated file.
52+
If no title text is specified, the default title text is taken from the filename, formatted with sentence capitalization.
53+
54+
== Configuring your project
55+
56+
You'll need to update the following for your project
57+
58+
=== antora.yml
59+
60+
- `name:` - replace `docs-template` with the name of the project as it will appear in the URL https://neo4j.com/docs/<PROJECT_NAME>`, for example 'getting-started', 'cypher-manual'.
61+
- `title:` - the title of the manual, for example Getting Started Guide, Cypher Manual. This value is displayed in the breadcrumbs above each page.
62+
- `version:` - the version of the content that is generated from the branch containing this `antora.yml` file.
63+
64+
Optionally, you can add the following attributes:
65+
66+
- `display_version:` - Use this attribute when you want the version that is displayed in your content and in the UI to be different from the version that appears in the URL. For example, you might want to use _/2.0/_ in URLs, but display the version as `2.0-beta` in the version selector drop-down.
67+
- `prerelease:` - if you publish multiple versions of this project, you can mark a version as being a prerelease, by adding `prerelease: true`. The content is published alongside the other versions, but does not appear in the drop-down version selector, and is not included when Antora is calculating the default (or 'latest') version in order to resolve links between pages. For more information, see link:https://docs.antora.org/antora/latest/component-prerelease/[Antora // Docs -> Identify a Prerelease Version]
68+
69+
=== preview.yml
70+
71+
Antora uses a link:https://docs.antora.org/antora/latest/playbook/[playbook] to determine what content is included in a site, and the appearance of that content.
72+
73+
In our projects, we use `preview.yml` as the default playbook name.
74+
75+
Update the `start_page` attribute to match the value of the `name` attribute in your `antora.yml` file.
76+
77+
----
78+
site:
79+
start_page: docs-template:ROOT:index.adoc
80+
----
81+
82+
Update the information for the sitemap extension:
83+
84+
----
85+
antora:
86+
extensions:
87+
- require: "@neo4j-antora/antora-modify-sitemaps"
88+
sitemap_version: '1.0'
89+
sitemap_loc_version: 'current'
90+
move_sitemaps_to_components: true
91+
----
92+
93+
The link:https://www.npmjs.com/package/@neo4j-antora/antora-modify-sitemaps[`antora-modify-sitemaps`] Antora extension generates sitemaps for Neo4j docs that include information about the current release only, and makes sure those sitemaps are included in the right output folder when the HTML is built.
94+
In this example, a sitemap file would be generated at _build/site/docs-template/1.0/sitemap.xml_.
95+
Change the value of `sitemap_version` to the 'current' release version of your project.
96+
For example, Neo4j manuals such as the Getting Started Guide or Cypher Manual use 4.4 as their current version, so for those manuals this is set as `sitemap_version: '4.4`.
97+
98+
=== [Optional] Add an 'Edit this page' link
99+
100+
If your repo is public, you can add an `Edit this page` link to your pages to encourage external contributors, and to provide a quick way for users to suggest changes.
101+
102+
Update the following attribute in your playbook:
103+
104+
----
105+
asciidoc:
106+
attributes:
107+
page-origin-private: false
108+
----
109+
110+
=== [Optional] Add a 'preview' note to each page
111+
112+
When we publish preview content to either development or production environments, we prepend an admonition to every page to make it clear that this is preview content, for example, as in link:https://neo4j.com/docs/graph-data-science/2.0-preview/[Graph Data Science 2.0-preview].
113+
114+
You can use the link:https://www.npmjs.com/package/@neo4j-antora/antora-add-notes[antora-add-notes] extension to add content to your pages.
115+
Follow the Usage instructions in the package documentation.

‎antora.yml

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
name: docs-template
2+
title: Neo4j Documentation template
3+
version: '1.0'
4+
# display_version: '1.0-preview'
5+
start_page: ROOT:index.adoc
6+
nav:
7+
- modules/ROOT/content-nav.adoc

‎modules/ROOT/content-nav.adoc

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
* xref:index.adoc[]
2+
* xref:getting-started.adoc[]
3+
* xref:content-types.adoc[]
4+
* xref:trademarks.adoc[]

‎modules/ROOT/examples/example.csv

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Field1,Field2
2+
Value1,Value2

‎modules/ROOT/pages/content-types.adoc

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
= Content types
2+
3+
== Pages
4+
5+
To add a page, create a new asciidoc file in _modules/ROOT/pages_.
6+
Then add a link to the new file in _modules/ROOT/content-nav.adoc_.
7+
8+
For example:
9+
10+
----
11+
* xref:index.adoc[]
12+
* xref:getting-started.adoc[]
13+
* xref:content-types.adoc[]
14+
----
15+
16+
For more information about pages, see link:https://docs.antora.org/antora/latest/page/[Antora Docs -> Pages].
17+
18+
== Partials
19+
20+
Partials are reusable asciidoc fragments that can be included in a page, or in another partial.
21+
Partials are stored in _modules/ROOT/partials.
22+
23+
.Including asciidoc content from a partial:
24+
====
25+
26+
Asciidoc:
27+
28+
----
29+
\include::partial$reusing-content.adoc[]
30+
----
31+
32+
Output:
33+
34+
--
35+
include::partial$reusing-content.adoc[]
36+
--
37+
====
38+
39+
For more information about partials, see link:https://docs.antora.org/antora/latest/page/partials/[Antora Docs -> Partials].
40+
41+
== Examples
42+
43+
Examples are stored in _modules/ROOT/examples.
44+
45+
.Including a CSV file:
46+
====
47+
48+
Asciidoc:
49+
50+
----
51+
\include::example$example.csv[]
52+
----
53+
54+
Output:
55+
56+
----
57+
include::example$example.csv[CSV Example]
58+
----
59+
====
60+
61+
62+
== Images
63+
64+
Images are stored in _modules/ROOT/images.
65+
66+
.Including an image:
67+
====
68+
69+
Asciidoc:
70+
71+
----
72+
image::image.svg[]
73+
----
74+
====

‎modules/ROOT/pages/getting-started.adoc

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
= Getting Started
2+
3+
This repo contains the files that you need to start a new Neo4j documentation project.
4+
5+
== antora.yml
6+
7+
- `name:` - replace `docs-template` with the name of the project as it will appear in the URL https://neo4j.com/docs/<PROJECT_NAME>`, for example 'getting-started', 'cypher-manual'.
8+
- `title:` - the title of the manual, for example Getting Started Guide, Cypher Manual. This value is displayed in the breadcrumbs above each page.
9+
- `version:` - the version of the content that is generated from the branch containing this `antora.yml` file.
10+
11+
Optionally, you can add the following attributes:
12+
13+
- `display_version:` - Use this attribute when you want the version that is displayed in your content and in the UI to be different from the version that appears in the URL. For example, you might want to use _/2.0/_ in URLs, but display the version as `2.0-beta` in the version selector drop-down.
14+
- `prerelease:` - if you publish multiple versions of this project, you can mark a version as being a prerelease, by adding `prerelease: true`. The content is published alongside the other versions, but does not appear in the drop-down version selector, and is not included when Antora is calculating the default (or 'latest') version in order to resolve links between pages. For more information, see link:https://docs.antora.org/antora/latest/component-prerelease/[Antora Docs -> Identify a Prerelease Version]
15+
16+
== preview.yml
17+
18+
Antora uses a link:https://docs.antora.org/antora/latest/playbook/[playbook] to determine what content is included in a site, and the appearance of that content.
19+
20+
In our projects, we use `preview.yml` as the default playbook name.
21+
22+
Update the `start_page` attribute to match the value of the `name` attribute in your `antora.yml` file.
23+
24+
----
25+
site:
26+
start_page: docs-template:ROOT:index.adoc
27+
----
28+
29+
Update the information for the sitemap extension:
30+
31+
----
32+
antora:
33+
extensions:
34+
- require: "@neo4j-antora/antora-modify-sitemaps"
35+
sitemap_version: '1.0'
36+
sitemap_loc_version: 'current'
37+
move_sitemaps_to_components: true
38+
----
39+
40+
The link:https://www.npmjs.com/package/@neo4j-antora/antora-modify-sitemaps[`antora-modify-sitemaps`] Antora extension generates sitemaps for Neo4j docs that include information about the current release only, and makes sure those sitemaps are included in the right output folder when the HTML is built.
41+
In this example, a sitemap file would be generated at _build/site/docs-template/1.0/sitemap.xml_.
42+
Change the value of `sitemap_version` to the 'current' release version of your project.
43+
For example, Neo4j manuals such as the Getting Started Guide or Cypher Manual use 4.4 as their current version, so for those manuals this is set as `sitemap_version: '4.4`.
44+
45+
== [Optional] Add an 'Edit this page' link
46+
47+
If your repo is public, you can add an `Edit this page` link to your pages to encourage external contributors, and to provide a quick way for users to suggest changes.
48+
49+
Update the following attribute in your playbook:
50+
51+
----
52+
asciidoc:
53+
attributes:
54+
page-origin-private: false
55+
----
56+
57+
== [Optional] Add a 'preview' note to each page
58+
59+
When we publish preview content to either development or production environments, we prepend an admonition to every page to make it clear that this is preview content, for example, as in link:https://neo4j.com/docs/graph-data-science/2.0-preview/[Graph Data Science 2.0-preview].
60+
61+
You can use the link:https://www.npmjs.com/package/@neo4j-antora/antora-add-notes[antora-add-notes] extension to add content to your pages.
62+
Follow the Usage instructions in the package documentation.

‎modules/ROOT/pages/index.adoc

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
= Docs template
2+
3+
This is the main index page for your docs project.
4+
5+
== Start page
6+
7+
When you build your content locally, this page should be specified as the start page in _preview.yml_.
8+
9+
[source, yaml, role=noheader]
10+
----
11+
start_page: docs-template:ROOT:index.adoc
12+
----
13+
14+
[TIP]
15+
====
16+
This repo contains example content such as asciidoc pages, re-usable fragments, and examples, to show where different types of files should be stored in an Antora project.
17+
====

‎modules/ROOT/pages/trademarks.adoc

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
= Registered trademarks
2+
3+
We use the link:https://www.npmjs.com/package/@neo4j-antora/mark-terms[`@neo4j-antora/mark-terms`] extension to mark the first usage of the following terms:
4+
5+
* Cypher
6+
7+
The list of terms marked is configured by the `page-terms-to-mark` attribute in playbooks.

‎modules/ROOT/partials/reusing-content.adoc

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
This paragraph can be used anywhere with the syntax shown in xref:content-types.adoc#_partials[].

0 commit comments

Comments
 (0)