All the documentation is published on https://www.ans.co.uk/docs/
If you would like to contribute a guide or amendment to an existing one, please fork the repository and submit a pull request.
To get started, please visit:
There are a number of ways you can develop locally.
You can also use the docker-compose.dev.yml
Docker Compose file, which will build a full environment, including Elasticsearch and populating it. For making small changes, however, you might find this tedious as you will need to rebuild the containers on every change.
Generally, the easiest way is to run sphinx-autobuild
, which will give you a live preview of the ANS Docs site using your local data. This automatically rebuilds any changed docs content.
This does have some drawbacks. Firstly, only content in the /source
directory is auto-rebuilt, so no theme CSS or JavaScript. They are rendered at at the start, but changes are not detected. Secondly, there is no search functionality possible.
One of the easiest ways is to use a Linux server with Docker installed. Using the command below will start up a container, map in the current directory and set up port forwarding for 8000/tcp
, as defined in docker-compose.devlocal.yml
.
docker-compose -f docker-compose.devlocal.yml up -d
Once the container has started up fully (which can take a few minutes), you should be able to browse to http://127.0.0.1:8000
and see content. If you want to access the content remotely, replace 127.0.0.1
with the correct IP of your Linux server.
If you need to see the build logs, you can do so with:
docker logs sphinx_autobuild
You can install all the dependencies to run Sphinx using the commands in the Autobuild-Dockerfile
file. Generally, however, you will need to have these packages installed:
- Package Manager |
make
, Python 3.6+ - PIP |
sphinx-autobuild
,recommonmark
Once those are in place, you should be able to start sphinx-autobuild
like this:
sphinx-autobuild \
--pre-build "make build/html/_static/css/app.css" \
--pre-build "make build/html/_static/app.js" \
--host 0.0.0.0 \
source build/html
There are a few commands you can use to check the content is correct:
This will go through the content and make sure there are no broken links within the content.
make linkcheck
If you're using Docker for development, you can run this to check whether the content meets the linting requirements:
docker run \
-v "$PWD:/app" \
-w /app \
--rm \
markdownlint/markdownlint source
We are using PySpelling for this. Similarly, if you're using Docker for development, you can run this to check whether the content meets the spell check requirements:
docker run \
-v "$PWD:/app" \
-w /app \
--rm \
-e INPUT_SOURCE_FILES="source/**/*.md" \
-e INPUT_TASK_NAME=Markdown \
rojopolis/spellcheck-github-actions:0.10.0
You can change the $INPUT_SOURCE_FILES
variable to be whatever you want. It will accept a space-separated list of files.
There are two word lists in place which control the spell checking:
-
The first is
.wordlist.txt
which has all of the words we use in ANS and the IT field in it. You should add more words to this, but only if they are legitimate and correct in terms of upper and lower case. -
The second is
.wordlist-workaround.txt
which contains non-words and partial words to work around limitations in PySpelling.One example of this is
L2TP
. Asaspell
(which powers PySpelling) splits words first on non-word characters,L2TP
is seen as two different words,L
andTP
. Similarly, word contractions likeANS's
will we seen as invalid, as will hyphenated words.So, you should add these workarounds to this file, not the
.wordlist.txt
file.
You can also wrap words with the HTML tag <nospell>
, which will cause PySpelling to ignore the word.
Please ensure pages and folders are easy to read and sensibly structured.
Please keep the page URLs lowercase and use hyphens instead of spaces, e.g.
/docs/desktop/fastdesk/getting-started/windows/
When adding a new page these elements need to be considered to help site readability, usability, navigation and search results. Here's info on what each does, how to set them and some guidelines.
Sets the main heading for the page
.. image:: https://user-images.githubusercontent.com/30502984/86182420-d9c66d00-bb27-11ea-929f-5b4025c6e6b1.png
:width: 500
To set:
- Within
.md
files (normal content pages), add as first piece of content.
# Transferring a Domain to ANS
- Within
index.rst
files (category index pages, which list the.md
pages underneath), add to top of file.
======================
Domain Name Management
======================
The h1
tag is the title of the article and should give the reader a strong sense of what they are going to read. It should be between 20 and 70 characters, but this is not enforced. There should only be one h1
-level heading on a page, and it should be the first on the page.
By default the page navigation and breadcrumb is populated from the Page Heading, and often this is perfectly fine. Sometimes, a longer page heading is better for the user, but long sentences will fill up the nav
and push the breadcrumbs off the page. If you want a longer page title (h1
), set the nav
item specifically, as shown:
You can override the name of the page in the Table of Contents and sidebar too. Those are defined in index.rst
files. Use the format Page Title <filename-on-disk-minus-extension>
to achieve that, for example:
.. toctree::
:maxdepth: 1
Transfering to ANS <transferin>
Transfering from ANS <transferout>
Changing Nameservers <changingnameservers>
DNS Propagation <dnspropagation>
This meta content determines how the page is displayed in search engine results. It's crucial for the overall performance of the website from an SEO perspective and it helps the user with history, bookmarks and the site search.
.. image:: https://user-images.githubusercontent.com/30502984/86184852-e1d4db80-bb2c-11ea-82d7-7ac5938aa705.png
:width: 500
.. image:: https://user-images.githubusercontent.com/30502984/86185226-c0282400-bb2d-11ea-9eeb-a086c17d2a45.png
:width: 500
This is how they are displayed to the user in the site search results
.. image:: https://user-images.githubusercontent.com/30502984/86186022-d6cf7a80-bb2f-11ea-80c0-94ac1342e28e.png
:width: 500
In many cases the meta title can be the same as the Page Heading. However, there are character length limitations we must adhere to, so they may require shortening.
Also, give the content a description as this can help search results. Of course, though, the page content is much more important.
Please note spacing and indents are important, so copy this template.
Meta content looks like this and goes at the bottom of the file:
```eval_rst .. title:: Creating an eCloud Flex instance .. meta:: :description: Detailed guidance on creating OpenStack instances on eCloud Flex :keywords: openstack, ecloud flex, ans, nova, instance, virtual machine, vm ```
Meta content goes at the top of the page, otherwise it will fail our automated checks
.. title:: Email | Email hosting .. meta:: :description: Information regarding a wide range of email related issues :keywords: ans, email, exim, postfix, mail, dovecot, blocklist, dkim, spf
As you'll see, the content is the same except for being wrapped in an eval_rst
fence.
title
- maximum of 42 characters. Don't include "| ANS Documentation" at the end as this is will be added via the template.description
- maximum of 165 characters
Your pull request will fail the automated checks without this meta content in the correct format.
Most content is simple Markdown (md
), but some features require reStructuredText (rst
). The format is quite different compared to Markdown, and needs to be inside eval_rst
blocks. Here are a few examples of how to add more types of content.
Where relevant, please add screenshots to pages as image files (ideally .png
). This is especially useful when describing how to complete a task in Myans, for instance. Please blur out any sensitive information such as account names or IP addresses, as necessary. Most image editors will allow you to add a blurred box over the image. This looks a lot neater than using a "black marker pen" style.
Given the following structure:
.
├── document.md
├── files
│ ├── image.png
We can include image.png
in document.md
using Markdown as below (with someimage
becoming the alt
text):
![someimage](files/image.png)
Or using reStructuredText (to control height and width) as below:
```eval_rst .. image:: files/image.png :width: 400 ```
Example image, the text preceding becomes the Alt text
.. note:: Tables need to be in reStructuredText format otherwise they won't display properly when published. It _will_ look fine in Git, but will look horrible when published, trust me!
There are free tools that will generate RST for you, like http://www.tablesgenerator.com/text_tables#.
This is an example which works. Note the requirement to wrap in the eval_rst
fence block.
```eval_rst =========== ======== ========================================================= Record Type Hostname Target =========== ======== ========================================================= CNAME portal 64cf9871a5b0ca045an96udtf9a63687c180f47df6.user.ddosx.com =========== ======== ========================================================= ```
For internal site links the easiest form to add them is like this:
- In Markdown
If you wish to use text other than the heading for the section that you're linking to, use the following format:
- For internal links
[text to show](link-to-page)
- For external links
[Go to the domain transfer in page in ANS Portal](https://portal.ans.co.uk/domains/transfer-in.php).
- In reStructuredText
:doc:`/ecloud/flex/general/openstackcli`
This will make a hyperlink using the title of the page /docs/ecloud/flex/general/openstackcli
as the text.
If you wish to use text other than the heading for the section that you're linking to, use the following format:
:doc:`Custom Text</ecloud/flex/general/openstackcli>`
You can also use this syntax:
`Custom Text</docs/ecloud/flex/general/openstackcli>`_
If you need to link headings (anchors) in other pages, you may need to use this format, which separates the display text away from the hyperlink target:
.. note::
Please see our user guide on `connecting to your website via FTP`_ for further assistance.
.. _connecting to your website via FTP: /docs/operatingsystems/windows/commonissues/copyfiletoserver#connecting-to-your-ftp-server
You'll notice that connecting to your website via FTP
is used as a reference to associate the two.
.. warning::
Avoid using words like 'link', 'click here' or 'here' as the linking text. These are harder to pick out for the user, and offer no idea of where the link will take them unless they read the preceeding content, which makes it harder. The text should give a good idea to the user where it will take them when reading it alone.
These must be done using reStructuredText, and the format is like this:
```eval_rst .. note:: Sectigo also provide an online EV click-through as an alternative. This is available on request. ```
See the file in path /domains/ssl/extended_validation_ssl
as an example.
Adding this:
DDoSX\ :sup:`®`\
Renders like this: DDoSX®
Ensure you have docker
and docker-compose
installed.
git clone https://github.com/ans-group/docs.ukfast.co.uk.git ans_docs
cd ans_docs
docker-compose -f docker-compose.dev.yml up --build
Open a browser to 'http://localhost/docs'