You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2026/08/06 17:03:05 UTC
(maven-scm-publish-plugin) branch master updated (987d06f -> a0d1662)
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/maven-scm-publish-plugin.git
from 987d06f Enable Maven 4 (#152)
new b9d595d Rename the site documents ahead of converting them
new a0d1662 Port the site documentation from APT to Markdown
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
src/site/apt/examples/importing-maven-site.apt | 66 -----------
.../apt/examples/multi-module-configuration.apt.vm | 72 ------------
.../apt/examples/one-module-configuration.apt.vm | 61 ----------
src/site/apt/index.apt.vm | 112 ------------------
src/site/apt/usage.apt.vm | 41 -------
src/site/apt/various-tips.apt.vm | 125 ---------------------
src/site/markdown/examples/importing-maven-site.md | 53 +++++++++
.../examples/multi-module-configuration.md | 59 ++++++++++
.../examples/one-module-configuration.md.vm | 51 +++++++++
src/site/markdown/index.md | 68 +++++++++++
.../src/site/site.xml => site/markdown/usage.md} | 33 +++---
src/site/markdown/various-tips.md.vm | 115 +++++++++++++++++++
12 files changed, 360 insertions(+), 496 deletions(-)
delete mode 100644 src/site/apt/examples/importing-maven-site.apt
delete mode 100644 src/site/apt/examples/multi-module-configuration.apt.vm
delete mode 100644 src/site/apt/examples/one-module-configuration.apt.vm
delete mode 100644 src/site/apt/index.apt.vm
delete mode 100644 src/site/apt/usage.apt.vm
delete mode 100644 src/site/apt/various-tips.apt.vm
create mode 100644 src/site/markdown/examples/importing-maven-site.md
create mode 100644 src/site/markdown/examples/multi-module-configuration.md
create mode 100644 src/site/markdown/examples/one-module-configuration.md.vm
create mode 100644 src/site/markdown/index.md
copy src/{it/publish-scm-staged/src/site/site.xml => site/markdown/usage.md} (50%)
create mode 100644 src/site/markdown/various-tips.md.vm
(maven-scm-publish-plugin) 01/02: Rename the site documents ahead of converting them
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-scm-publish-plugin.git
commit b9d595de7f61e62391d9a95c42b1f0e4c92a048e
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Thu Aug 6 13:53:01 2026 +0200
Rename the site documents ahead of converting them
A pure rename, so that git records it and `git log --follow` and `git blame` still
reach the history of each page after the conversion that follows. The content is
still APT at this point and the site does not build between the two commits.
---
.../examples/importing-maven-site.md} | 0
.../examples/multi-module-configuration.md} | 0
.../examples/one-module-configuration.md.vm} | 0
src/site/{apt/index.apt.vm => markdown/index.md} | 0
src/site/{apt/usage.apt.vm => markdown/usage.md} | 0
src/site/{apt/various-tips.apt.vm => markdown/various-tips.md.vm} | 0
6 files changed, 0 insertions(+), 0 deletions(-)
diff --git a/src/site/apt/examples/importing-maven-site.apt b/src/site/markdown/examples/importing-maven-site.md
similarity index 100%
rename from src/site/apt/examples/importing-maven-site.apt
rename to src/site/markdown/examples/importing-maven-site.md
diff --git a/src/site/apt/examples/multi-module-configuration.apt.vm b/src/site/markdown/examples/multi-module-configuration.md
similarity index 100%
rename from src/site/apt/examples/multi-module-configuration.apt.vm
rename to src/site/markdown/examples/multi-module-configuration.md
diff --git a/src/site/apt/examples/one-module-configuration.apt.vm b/src/site/markdown/examples/one-module-configuration.md.vm
similarity index 100%
rename from src/site/apt/examples/one-module-configuration.apt.vm
rename to src/site/markdown/examples/one-module-configuration.md.vm
diff --git a/src/site/apt/index.apt.vm b/src/site/markdown/index.md
similarity index 100%
rename from src/site/apt/index.apt.vm
rename to src/site/markdown/index.md
diff --git a/src/site/apt/usage.apt.vm b/src/site/markdown/usage.md
similarity index 100%
rename from src/site/apt/usage.apt.vm
rename to src/site/markdown/usage.md
diff --git a/src/site/apt/various-tips.apt.vm b/src/site/markdown/various-tips.md.vm
similarity index 100%
rename from src/site/apt/various-tips.apt.vm
rename to src/site/markdown/various-tips.md.vm
(maven-scm-publish-plugin) 02/02: Port the site documentation from APT to Markdown
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-scm-publish-plugin.git
commit a0d166209346084ba975d4a4bb73916307325163
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Thu Aug 6 13:53:01 2026 +0200
Port the site documentation from APT to Markdown
9 page(s) converted with doxia-converter and then cleaned up by hand:
- <<<code>>> becomes backticks, <<bold>> becomes **bold**, {{{url}text}}
becomes [text](url)
- the ASF license header becomes a single block HTML comment
- a page whose only Velocity reference was ${project.name} is now a plain
.md with the title spelled out
- a page that keeps a reference stays a .vm. Velocity reads ## as a line
comment and would silently swallow every ATX heading below level one, so
subsections use setext underlines and anything deeper is wrapped in
#[[ ... ]]#
- references APT rendered literally are escaped, so they do not resolve
Verified by building the site before and after and comparing every
generated page: the visible text and the link targets are unchanged apart
from <b>/<i> becoming <strong>/<em> and quotes in prose picking up the
Markdown module's typographic substitution.
---
src/site/markdown/examples/importing-maven-site.md | 57 +++-----
.../examples/multi-module-configuration.md | 67 ++++-----
.../examples/one-module-configuration.md.vm | 54 +++-----
src/site/markdown/index.md | 152 ++++++++-------------
src/site/markdown/usage.md | 54 +++-----
src/site/markdown/various-tips.md.vm | 114 +++++++---------
6 files changed, 199 insertions(+), 299 deletions(-)
diff --git a/src/site/markdown/examples/importing-maven-site.md b/src/site/markdown/examples/importing-maven-site.md
index 3d44d9b..07ba4d1 100644
--- a/src/site/markdown/examples/importing-maven-site.md
+++ b/src/site/markdown/examples/importing-maven-site.md
@@ -1,42 +1,31 @@
- ------
- Importing maven.apache.org Content to Svn
- ------
- Hervé Boutemy
- ------
- 2012-08-19
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-Importing maven.apache.org Content to Svn
+# Importing maven.apache.org Content to Svn
- This plugin has been created to enable conversion of Maven components documentation
- to Apache CMS, based on svnpubsub: see {{{http://www.apache.org/dev/cms.html}documentation}}.
+This plugin has been created to enable conversion of Maven components documentation to Apache CMS, based on svnpubsub: see [documentation](http://www.apache.org/dev/cms.html).
- Once new content can be published with the plugin, existing content needs to be imported.
+Once new content can be published with the plugin, existing content needs to be imported.
- A little shell script has been used to import a component with all its versions independently of
- any site generation phase or components' pom.xml:
+A little shell script has been used to import a component with all its versions independently of any site generation phase or components' pom.xml:
-+--------
+```unknown
# configuration
ORIG_PATH=/www/maven.apache.org
DEST_SVN_BASE=https://svn.apache.org/repos/infra/websites/production/maven/content
@@ -45,7 +34,6 @@ ARTIFACT=maven-clean-plugin
DIR=plugins/${ARTIFACT}
VERSIONS="2.3 2.4 2.4.1 2.5"
-
# initialize ${DIR}-LATEST entry in svn
svn -m "prepare ${ARTIFACT} documentation publication" mkdir ${DEST_SVN_BASE}/${DIR}-LATEST
@@ -62,5 +50,4 @@ do
svn cp ${DEST_SVN_BASE}/${DIR}-LATEST ${DEST_SVN_BASE}/${DIR}-${VERSION} -m "releasing ${ARTIFACT} ${VERSION} documentation"
done
-+--------
-
\ No newline at end of file
+```
diff --git a/src/site/markdown/examples/multi-module-configuration.md b/src/site/markdown/examples/multi-module-configuration.md
index e1b4df5..93a05b9 100644
--- a/src/site/markdown/examples/multi-module-configuration.md
+++ b/src/site/markdown/examples/multi-module-configuration.md
@@ -1,55 +1,42 @@
- ------
- Maven Multi Module Configuration
- ------
- Olivier Lamy
- Hervé Boutemy
- ------
- 2012-12-06
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-Maven Multi Module Configuration
+# Maven Multi Module Configuration
- With a multi modules build, you cannot simply use <<<mvn site-deploy>>>: you must stage your site first.
+With a multi modules build, you cannot simply use `mvn site-deploy`: you must stage your site first.
- Cli commands to use:
+Cli commands to use:
-+------------+
+```shell
mvn -Preporting site site:stage
mvn scm-publish:publish-scm
-+------------+
+```
- These commands work well with mono-module too, even if mono-module could permit some optimizations (everything can be run
- in only one Maven invocation).
+These commands work well with mono-module too, even if mono-module could permit some optimizations (everything can be run in only one Maven invocation).
-* Avoiding Extra Path During Staging
+## Avoiding Extra Path During Staging
- When staging the site, sometimes extra directories may appear between <<<target/staging>>> and the effective root of the site:
- this is caused by the auto-detection algorithm of site root, which cannot detect at which level to stop.
+When staging the site, sometimes extra directories may appear between `target/staging` and the effective root of the site: this is caused by the auto-detection algorithm of site root, which cannot detect at which level to stop.
- This can be fixed by configuring the {{{/plugins/maven-site-plugin/stage-mojo.html#topSiteURL}site plugin's topSiteURL parameter}}
- (added in version 3.3) with top distribution management site url in a parent pom:
+This can be fixed by configuring the [site plugin's topSiteURL parameter](/plugins/maven-site-plugin/stage-mojo.html#topSiteURL) (added in version 3.3) with top distribution management site url in a parent pom:
-+-----+
+```xml
<distributionManagement>
<site>
<id>site</id>
@@ -69,4 +56,4 @@ mvn scm-publish:publish-scm
</plugins>
</pluginManagement>
</build>
-+-----+
+```
diff --git a/src/site/markdown/examples/one-module-configuration.md.vm b/src/site/markdown/examples/one-module-configuration.md.vm
index a483732..c1ab7e5 100644
--- a/src/site/markdown/examples/one-module-configuration.md.vm
+++ b/src/site/markdown/examples/one-module-configuration.md.vm
@@ -1,39 +1,29 @@
- ------
- Maven Mono Module Configuration
- ------
- Olivier Lamy
- Hervé Boutemy
- ------
- 2012-12-05
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-Maven Mono Module Configuration
+# Maven Mono Module Configuration
- <<This easy to use and optimized (no staging) configuration works only for mono module Maven build>>
+**This easy to use and optimized (no staging) configuration works only for mono module Maven build**
- With following configuration you can simply run: <<<mvn site-deploy>>>
+With following configuration you can simply run: `mvn site-deploy`
-+-----------------------
+```xml
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
@@ -46,7 +36,7 @@ Maven Mono Module Configuration
<artifactId>maven-scm-publish-plugin</artifactId>
<version>${project.version}</version>
<configuration>
- <content>\${project.reporting.outputDirectory}</content><!-- mono-module doesn't require site:stage -->
+ <content>${esc.d}{project.reporting.outputDirectory}</content><!-- mono-module doesn't require site:stage -->
</configuration>
<executions>
<execution>
@@ -58,4 +48,4 @@ Maven Mono Module Configuration
</execution>
</executions>
</plugin>
-+-----------------------
+```
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index b401d8c..6ce4dbb 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -1,112 +1,68 @@
- ------
- Introduction
- ------
- Benson Margulies
- ------
- 2013-07-22
- ------
-
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
-
-${project.name}
-
- The maven-scm-publish-plugin is a utility plugin to allow publishing Maven
- website to any supported SCM (Source Code Management) repository (like Git).
- The primary goal was to have an utility plugin to allow Apache projects
- to publish Maven websites via the {{{https://infra.apache.org/project-site.html#tools}ASF svnpubsub system}}.
-
- In addition to SCM operations, it takes care to fix newline inconsistencies
- generated by <<<maven-site-plugin>>> (see {{{https://issues.apache.org/jira/browse/MSITE-121}MSITE-121}}),
- which prevents simple content import to SCM.
-
- The plugin has been tested with Git SCM too and by example can
- {{{./various-tips.html#Git_branch}push content for GitHub Pages}}.
-
-
-* Implementation
-
- The plugin works from <<staged website>> by default (see {{{./publish-scm-mojo.html#content}<<<content>>> parameter}}).
-
- It first checks out the contents of a directory from
- the SCM (see {{{./publish-scm-mojo.html#pubScmUrl}<<<pubScmUrl>>> parameter}}) into
- <<<target/scmpublish-checkout>>> by default (see {{{./publish-scm-mojo.html#checkoutDirectory}<<<checkoutDirectory>>> parameter}}).
-
- Then locally staged content is applied to the check-out, issuing
- appropriate SCM commands to add and delete entries, followed by a
- check-in.
-
- The <<scmpublish.dryRun>> parameter to the plugin avoids all
- SCM operations, and simply logs out the added, deleted,
- and changed files.
-
- The <<scmpublish.skipCheckin>> parameter omits the final checkin.
- This allows you to visit <<<target/scmpublish-checkout>>>, and validate
- its contents before submitting to the SCM.
-
-* Publishing any content to SCM
-
- Even without any <<<pom.xml>>>/Maven project, you can update SCM content with
- a local content:
-
-+-------+
-mvn scm-publish:publish-scm -Dscmpublish.pubScmUrl=scm:<scm-provider>... -Dscmpublish.content=...path-to-content...
-+-------+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Apache Maven SCM Publish Plugin
+The maven-scm-publish-plugin is a utility plugin to allow publishing Maven website to any supported SCM (Source Code Management) repository (like Git). The primary goal was to have an utility plugin to allow Apache projects to publish Maven websites via the [ASF svnpubsub system](https://infra.apache.org/project-site.html#tools).
+
+In addition to SCM operations, it takes care to fix newline inconsistencies generated by `maven-site-plugin` (see [MSITE-121](https://issues.apache.org/jira/browse/MSITE-121)), which prevents simple content import to SCM.
+
+The plugin has been tested with Git SCM too and by example can [push content for GitHub Pages](./various-tips.html#Git_branch).
- SCM content will be checked-out to a temporary directory, then local content will
- be applied to the check-out, before it is checked-in back.
+## Implementation
- See {{{./examples/importing-maven-site.html}maven.apache.org content import script}} for an
- example.
+The plugin works from **staged website** by default (see [`content` parameter](./publish-scm-mojo.html#content)).
- <<See {{{./various-tips.html}Some Tips}}.>>
+It first checks out the contents of a directory from the SCM (see [`pubScmUrl` parameter](./publish-scm-mojo.html#pubScmUrl)) into `target/scmpublish-checkout` by default (see [`checkoutDirectory` parameter](./publish-scm-mojo.html#checkoutDirectory)).
-* Known Limitations
+Then locally staged content is applied to the check-out, issuing appropriate SCM commands to add and delete entries, followed by a check-in.
+
+The **scmpublish.dryRun** parameter to the plugin avoids all SCM operations, and simply logs out the added, deleted, and changed files.
+
+The **scmpublish.skipCheckin** parameter omits the final checkin. This allows you to visit `target/scmpublish-checkout`, and validate its contents before submitting to the SCM.
+
+## Publishing any content to SCM
+
+Even without any `pom.xml`/Maven project, you can update SCM content with a local content:
+
+```shell
+mvn scm-publish:publish-scm -Dscmpublish.pubScmUrl=scm:<scm-provider>... -Dscmpublish.content=...path-to-content...
+```
- There are 2 known limitations:
-
- * for Subversion, the plugin can create the initial SCM directory if it does not exist. But for Git by example, if you use a branch,
- the branch won't be created: you have to {{{./various-tips.html#Git_branch}create it manually}},
+SCM content will be checked-out to a temporary directory, then local content will be applied to the check-out, before it is checked-in back.
- * the plugin works well for multi-module websites publishing to a complete directory:
- you just need to publish <<<mvn site:stage>>> content. But if one module does not publish
- its content to the same directory (like Surefire or Enforcer, which have a
- base directory and one plugin in <<</plugins/>>>), this staging area can't be simply imported.
+See [maven.apache.org content import script](./examples/importing-maven-site.html) for an example.
- []
+**See [Some Tips](./various-tips.html).**
-* Future Dreams
+## Known Limitations
- Ideally, scm urls would be supported in <<<\<distributionManagement>>>> section of the POM, then
- publishing would simply be <<<mvn site-deploy>>>, without any problems for non-flat multi-modules
- sites.
+There are 2 known limitations:
- To reach such a dream, there are some steps:
+- for Subversion, the plugin can create the initial SCM directory if it does not exist. But for Git by example, if you use a branch, the branch won't be created: you have to [create it manually](./various-tips.html#Git_branch),
+- the plugin works well for multi-module websites publishing to a complete directory: you just need to publish `mvn site:stage` content. But if one module does not publish its content to the same directory (like Surefire or Enforcer, which have a base directory and one plugin in `/plugins/`), this staging area can't be simply imported.
+## Future Dreams
- * fix inconsistent newlines generated by <<<maven-site-plugin>>> (caused by <<<site.vm>>> template and
- resources taken from skin jar without fixing newlines): {{{https://issues.apache.org/jira/browse/MSITE-121}MSITE-121}}
- is fixed in maven-site-plugin 3.4,
+Ideally, scm urls would be supported in `<distributionManagement`> section of the POM, then publishing would simply be `mvn site-deploy`, without any problems for non-flat multi-modules sites.
- * improve {{{/wagon/wagon-providers/wagon-scm/}<<<wagon-scm>>>}} to put a whole directory content
- in one commit, and not with one commit per file.
+To reach such a dream, there are some steps:
- []
+- fix inconsistent newlines generated by `maven-site-plugin` (caused by `site.vm` template and resources taken from skin jar without fixing newlines): [MSITE-121](https://issues.apache.org/jira/browse/MSITE-121) is fixed in maven-site-plugin 3.4,
+- improve [`wagon-scm`](/wagon/wagon-providers/wagon-scm/) to put a whole directory content in one commit, and not with one commit per file.
- Then this plugin would be outdated, replaced by natural <<<maven-site-plugin:deploy>>> goal.
+Then this plugin would be outdated, replaced by natural `maven-site-plugin:deploy` goal.
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
index 115ad6e..d6464e7 100644
--- a/src/site/markdown/usage.md
+++ b/src/site/markdown/usage.md
@@ -1,41 +1,31 @@
- ------
- Usage
- ------
- Benson Margulies
- ------
- 2012-02-25
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Usage
-Usage
+The maven-scm-publish-plugin submits modified content to SCM, sites being the most classical case.
- The maven-scm-publish-plugin submits modified content to SCM, sites being the most classical case.
+The standard use for sites is:
- The standard use for sites is:
-
-+-----------+
+```shell
mvn -Preporting site site:stage
mvn scm-publish:publish-scm
-+-----------+
+```
- which will work both for multi-and mono-modules sites.
+which will work both for multi-and mono-modules sites.
diff --git a/src/site/markdown/various-tips.md.vm b/src/site/markdown/various-tips.md.vm
index 72510fa..90bd443 100644
--- a/src/site/markdown/various-tips.md.vm
+++ b/src/site/markdown/various-tips.md.vm
@@ -1,61 +1,54 @@
- ------
- Various Tips
- ------
- Olivier Lamy
- ------
- 2012-09-04
- ------
-
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
-
-Various tips for using this plugin
-
-* URL format
-
- You must use a scm url format:
-
-+----------------+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Various tips for using this plugin
+
+URL format
+----------
+
+You must use a scm url format:
+
+```unknown
scm:<scm_provider><delimiter><provider_specific_part>
-+----------------+
+```
- Example for svn: <<<scm:svn:https://svn.apache.org/repos/infra/websites/production/maven/content/plugins/maven-scm-publish-plugin/>>>
+Example for svn: `scm:svn:https://svn.apache.org/repos/infra/websites/production/maven/content/plugins/maven-scm-publish-plugin/`
- And configure is as it:
+And configure is as it:
-+----------------+
+```xml
<distributionManagement>
<site>
<id>site_id</id>
<url>scm:svn:https://svn.apache.org/repos/infra/websites/production/maven/content/plugins/maven-scm-publish-plugin/</url>
</site>
</distributionManagement>
-+----------------+
+```
- <<NOTE>>: with svn, if the remote url doesn't exist, it will be created.
+**NOTE**: with svn, if the remote url doesn't exist, it will be created.
-* Git branch
+Git branch
+----------
- To use Git branch (for example: {{{https://help.github.com/articles/user-organization-and-project-pages/}GitHub <<<gh-pages>>>}})
+To use Git branch (for example: [GitHub `gh-pages`](https://help.github.com/articles/user-organization-and-project-pages/))
-+----------------+
+```xml
<distributionManagement>
<site>
<id>site_id</id>
@@ -71,25 +64,24 @@ Various tips for using this plugin
<scmBranch>gh-pages</scmBranch>
</configuration>
</plugin>
-+----------------+
-
- <<Initial creation of the branch has to be done manually>>, as a Git orphan branch:
+```
- 1. <<<git checkout --orphan gh-pages>>> to create the branch locally,
+**Initial creation of the branch has to be done manually**, as a Git orphan branch:
- 2. <<<rm .git/index ; git clean -fdx>>> to clean the branch content and let it empy,
+1\. `git checkout --orphan gh-pages` to create the branch locally,
- 3. copy an initial site content,
+2\. `rm .git/index ; git clean -fdx` to clean the branch content and let it empy,
- 4. commit and push: <<<git add *>>>, <<<git commit -m "initial site content">>>, <<<git push>>>
+3\. copy an initial site content,
- []
+4\. commit and push: `git add *`, `git commit -m "initial site content"`, `git push`
-* Improving SCM Checkout Performance
+Improving SCM Checkout Performance
+----------------------------------
- By default, a complete checkout is done. You can configure the plugin to try update rather than a full checkout/clone
+By default, a complete checkout is done. You can configure the plugin to try update rather than a full checkout/clone
-+----------------+
+```xml
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-scm-publish-plugin</artifactId>
@@ -98,18 +90,16 @@ Various tips for using this plugin
<tryUpdate>true</tryUpdate>
</configuration>
</plugin>
-+----------------+
+```
- By default, the scm content is checked-out/cloned to <<<$\{project.build.directory}/scmpublish-checkout>>>, so when running <<<mvn clean>>>,
- all the content is deleted. You can configure a path to your machine to avoid full checkout.
- A recommended way is to use a property with a default value that your colleague will be able to override in their settings.
+By default, the scm content is checked-out/cloned to `${esc.d}{project.build.directory}/scmpublish-checkout`, so when running `mvn clean`, all the content is deleted. You can configure a path to your machine to avoid full checkout. A recommended way is to use a property with a default value that your colleague will be able to override in their settings.
-+----------------+
+```xml
<properties>
...
<!-- override in your settings -->
<siteMainDirectory>${user.home}</siteMainDirectory>
- <scmPubCheckoutDirectory>\${siteMainDirectory}/my-site-content-scm</scmPubCheckoutDirectory>
+ <scmPubCheckoutDirectory>${esc.d}{siteMainDirectory}/my-site-content-scm</scmPubCheckoutDirectory>
...
</properties>
@@ -122,4 +112,4 @@ Various tips for using this plugin
<tryUpdate>true</tryUpdate>
</configuration>
</plugin>
-+----------------+
+```