arxiv / arxiv-docs

Help, about and other static pages

info.arxiv.org pages

Help, about, policy and other pages for arXiv.

Overview

This is where to make edits to the about, help, labs, new and other pages at info.arxiv.org. These are written in markdown and turned into HTML pages with mkdocs-material.

How to do a Quick Edit on github

To make a quick edit, use this is a 4 step process:

1. Make your edit and commit to a new branch.

2. Make a PR from your branch to develop, get that reviewed.

3. Merge the PR to develop.

4. Merge changes on develop to master.
   
   

1. Make your edit on github

• To edit a page first go to the info.arxiv.org page you want to edit.
  Example: https://info.arxiv.org/help/gzip.html

• Click on the pencil icon to edit the page. That will take you to the corresponding page in github.

• On the page you want to edit in github, click the pencil to edit the page contents right in github.

• After you have made changes, click preview to see how it will look when completed.
  Please note: Github uses "Github flavored markdown" which is different from the markdown we use to create our documentation. There may be small variations in how the markdown appears due to these differences.

• Review your work in preview mode. To return to editing, click on "edit" in the header.

• Once you are happy with your changes you can save by clicking on the "Commit changes" button in the upper right hand corner. Commit is the term github and git use for saving.

• Add a brief note in the "Commit message" area summarizing your edit. You may add longer note in the "Extended description" area if you have more to say about your changes.

• Make sure you have your email associated with your commits.

• Note that a "new branch for this request and start a pull request" will be selected.

• Name your branch after your JIRA ticket (if applicable) or after your github username and brief description.
  Examples:
  arxivce-1503-update-arxiv-docs-readme
alisonhofer-update-arxiv-docs-readme

If you have more changes to make at this time you may make and commit them all to the branch you created. The additional changes you commit will be grouped together when you make your pull request in the next step.

2. Make a Pull Request from your branch to develop

Once you have completed all of your changes, you need to have your changes reviewed. This is done by "creating a PR." PR stands for pull request.

• At the top of your page you will notice a yellow box that will have the name of your commit and a button to the right of it that says "Compare & pull request".

• Click on Compare & pull request

In the event that you have made a commit and were unable to complete or create your pull request at the time, you will not have the same yellow box interface if you return to the page the next day.

You will have to make a pull request by clicking on the "Pull requests" link in the header of the github
Next, click the button to the right that says "New pull request"

• Compare your changes by clicking on the "compare:develop" dropdown and type in your branch name and then select your branch.
• This will compare your branch to the develop branch.

• Click on the "Files Changed" tab to view a comparison of the develop branch you are planning to merge into master.

• Click "Create pull request"
• Add a title for your pull request and a description if the title is not self explanatory.
• To the right, click on the gear icon to the right of "Reviewers".
• A dropdown will appear and request people to review your PR.
• If you are unsure who to ask to review your changes, check with your manager.

• After selecting reviewers, click the blue "Create pull request" button.

• Reviewers will receive an email from Github with a link to the PR to review.
• Additionally, you can slack your reviewers with a link to your PR to give them a heads up.

3. Merge the PR to develop

• Once your PR has been reviewed and approved you will receive an email notification with a link to your PR.
• Now you can merge your PR to develop.
• Open your PR and scroll down and click on "Merge pull request".

• You will be prompted to confirm you decision, click "Confirm merge".

  

• Please note: The above step will only put your changes on develop and they will not be viewable on the live site: info.arxiv.org. At this point you have only saved the edit(s) in github.

• You can review your changes on the develop site at info.dev.arxiv.org.

4. Make a Pull Request from develop to master

Please note: Once you have merged your changes to develop, it is important to deploy them as soon as possible. Lingering commits on on the develop branch can cause unintentional problems when they are deployed with other code. If you notice commits other than your own in the PR you make, please be sure to check in with the owners of those commits to ensure they are ready to go live.

• Now that your PR has been merged to develop, you need to deploy these changes to master.
• To make a new PR click the "Pull requests" link in the header of the github page.
• On the right hand side, click the blue button that says "New pull request"

• Compare your changes by clicking on the "base:develop" dropdown on the left and type in "master" and then select it.
• This will compare your branch to the develop branch.

• Click on the "Files Changed" tab to view a comparison of the develop branch you are planning to merge into master.

• Click "Create pull request"

• Add a title for your pull request and a description if the title is not self explanatory.

• To the right, click on the gear icon to the right of "Reviewers"

• A dropdown will appear and you can request people to review your PR.

• After selecting reviewers, click the blue "Create pull request" button.

• Ping your reviewers in slack with a link to your PR and ask them to review it.

• Once your PR has been reviewed and approved you can merge your PR to master.

• Open your PR and scroll down and click on "Merge pull request".

• You will be prompted to confirm you decision, click "Confirm merge".

• You will see your changes on production about 15 minutes after you have confirmed your merge.

Authoring Markdown

See AUTHORING.md

Building on your local machine

Instead of using github to edit you can check all the files for arxiv-docs to your laptop to edit and preview.

git clone [email protected]:arXiv/arxiv-docs.git
cd arxiv-docs
python --version
# 3.8.12
python -m venv docs-venv
source docs-venv/bin/activate
pip install -r requirements.txt
mkdocs serve
google-chrome https://localhost:8000/index.html

Then you will have the site served locally with hot reloading on edits. In your browser, go to http://localhost:8000/index.html

Deployment to info.arxiv.org

Commits or merges to arxiv-docs master branch will deploy the site.

The cloud build YAML files combined with CloudBuild triggers in arxiv-production comprise the deployment pipeline for arxiv-docs.

Previews of PRs

PRs that will merge to the branch develop on the github repo arxiv-docs will deploy previews at https://storage.googleapis.com/arxiv-docs-prs/YOUR_BRANCH_NAME/about/index.html

Note that the home page specifically does not exist, but any other page can be accessed with its URL path. This preview can been seen by the public, everything in the github arxiv-docs repo can also be seen by the public.

Direct commits to the develop branch will not generate a preview.

Historical site content

See https://github.com/arXiv/arxiv-docs/releases for branches prior to 2023 when content was shifted to the source/ directory.

arxiv-docs's Issues

broken link on https://info.arxiv.org/help/

On https://info.arxiv.org/help/ the "Submit an Article" link is 404.

Here's a fix:

https://github.com/arXiv/arxiv-docs/pull/810/files

Turbo is on the right lane

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [..@turbo.]

Echo 🤑 🤗🤗 turbo.com and Vercel.com to merge this for better production
Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

@sammyfilly

anchors

How will we handle anchors in markdown? Straight html?

Can there be automatic anchors for each header?
## Heading Title turns into something like <a name="heading-title"></a><h2>Heading Title</h2>

Incorrect description of the build system

The utilities page states that arXiv uses teTeX as its LaTeX build system: https://github.com/arXiv/arxiv-docs/blob/1c8c5b2646dfa9c812ac5121a6e85d6f9c9a5a7e/mkdocs/docs/help/utilities.md#tex

This is outdated because the arXiv blog stated that arXiv uses TeXlive 2020 already in 2020: https://blog.arxiv.org/2020/11/12/error-detected-a-new-feature-helps-authors-submit-their-work/

Shall we have a favicon for info.arxiv?

Not sure if this is possible with the mkdocs config or not

Do past versions of pages need to be accessible?

Or is it sufficient that we are able to identify and retrieve the version internally?

"Submissions by Category" link broken at https://info.arxiv.org/help/stats/index.html

I think the markdown is correct??
- [Submissions by Category](/about/reports/submission_category_by_year.md)

but the link is not getting converted... it still appears as
<a href="[/about/reports/submission_category_by_year.md](https://info.arxiv.org/about/reports/submission_category_by_year.md)">Submissions by Category</a></li>

This page exists OK
https://info.arxiv.org/about/reports/submission_category_by_year.html

Links on https://info.arxiv.org/help/policies/format_requirements.html are broken

Describe the bug
All links in https://info.arxiv.org/help/policies/format_requirements.html are broken, they point out e.g. https://info.arxiv.org/help/moderation/index.md .

(I can't tell what's wrong, the link appears to be in the correct format and in other pages the .md suffix is used for links as well, and they render correctly.)

md tables not rendering

What it looks like on github

What it looks like in local docker view

unclear what the #filename.md# means

In this directory
https://github.com/arXiv/arxiv-docs/tree/develop/source/help/stats
there is
index.md which I updated to be current
there is also "#index.md#" which is not current.

If I see things with hashmarks like #filename.md# can they just be deleted? or are they part of mkdocs process?

Broken link on 3rd party submissions page

Describe the bug
Link to Microsoft Conference Management toolkit broken

To Reproduce
Steps to reproduce the behavior:

1. Go to https://info.arxiv.org/help/third_party_submission.html
2. Click on link
3. See error

Expected behavior
Reach the page described

useless

journal frequencies

how long it takes for the paper to be reviewed?

Create landing page

Content needs to be created for landing page
info.arxiv.org/index.html

Possibly just have that be the About index.html page?

Current version should be shown at bottom of page

"Submissions" help document is unavailable

https://info.arxiv.org/help/submit.md.html returns "File not found"

None of the links from https://info.arxiv.org/about/accessibility_html_papers.html work

Describe the bug
None of the links from https://info.arxiv.org/about/accessibility_html_papers.html work

To Reproduce
Go to https://info.arxiv.org/about/accessibility_html_papers.html work and click on one of paper links

Expected behavior
It would go to the paper

Desktop (please complete the following information):
-macOS

• Safari

Additional context
Should be fixed quickly since this is a newly released feature and it is a bit embarrassing that one cannot look at the canned examples you provided of HTML papers.

setup pretty urls - remove index.html and .html suffix requirements

We want to preserve the benefit of the legacy markdown display that allowed for urls like
arxiv.org/help/moderation

The MVP for mkdocs adds extra string to the urls that make them more difficult to share in daily operations and in outreach with print materials. For example that page turns into
arxiv.org/help/moderation/index.html

Logos download is hidden behind a registration link

Describe the bug
The logos download is hidden behind a registration link.

To reproduce
Steps to reproduce the behavior:

1. Go to the logos page
2. Click on any of the download links, e.g., Large Logomark in PNG format
3. Choose 'Not a part of Cornell-Ithaca & Cornell Tech'
4. Need to sign in to Box.com

Expected behavior
A download link which doesn't require registration.

Spelling error in API manual (<author>)

Describe the bug
The result object entry key is wrong, but provided by the API manual (https://info.arxiv.org/help/api/user-manual.html#_details_of_atom_results_returned)

To Reproduce
Steps to reproduce the behavior:

1. Do an arXiv search and get a results object.
2. Iterate over the generator for r in client.results.(search):
3. Try to print `r.author'
4. See error

Expected behavior
Output the author names. To get the expected behavior you have to r.authors with the 's'. In the API manual an 's' is missing.

Desktop (please complete the following information):

• OS: Linux
• Browser Firefox
• Version Not relevant

HTML render demo page - all links broken

Describe the bug
The URL structure used on the demo page for html rendering beta, all use links

https://browse.arxiv.org/latexml/2006.15991v2/2006.15991v2.html
Replacing /latexml/ with /html/ presents a correctly converted version of the paper,
https://browse.arxiv.org/html/2308.06262v1/2308.06262v1.html

However it still offers a worse rendering than the live version,
e.g. https://arxiv.org/html/2403.15388v2, available linked from https://arxiv.org/abs/2403.15388

To Reproduce
Steps to reproduce the behavior:

1. Open https://info.arxiv.org/about/accessibility_html_papers.html, info page about html preview rendering.
2. Visit any link. Notice 404.

Expected behavior
An html formatted render appears.

Screenshots -

Desktop (please complete the following information): N/A / all

Smartphone (please complete the following information): N/A / all

Additional context -

Xpdf section in /help/pdf.html is quite outdated

Describe the bug
See: https://info.arxiv.org/help/pdf.html

At the very least, Xpdf dropped support for t1lib as of release 3.03, dated 2011-aug-15, because

t1lib has some potential security holes, and hasn't been updated in years.

If Debian's security tracker is anything to go by, there were in fact a bunch of buffer overflows and such, including at least one actual Remote Code Execution vulnerabilities. (Thankfully nothing quite as bad as the malicious PDF -> arbitrary code execution in the Windows Kernel exploit chain for Adobe's Type 1 implementation, chronicled here: https://googleprojectzero.blogspot.com/2015/07/one-font-vulnerability-to-rule-them-all.html -- mostly because t1lib doesn't run in kernel mode -- but still enough to compromise the user's data.)

Anyway, I believe any recent-ish software called Xpdf is using FreeType to render both Type1 and TrueType outlines -- not t1lib and not the X server (at least for anything used in the document -- the GUI is another story).

arXiv documentation does not mention where a paper password can be recovered from

Is your feature request related to a problem? Please describe.

Currently, neither the Passwords documentation page (link) or the Authority records page (link) mention, where exactly a paper password can be recovered from. I just had to go to Google and StackExchange (specifically a comment by LudvigH of this answer) to find this out, so I could instruct a submitting author where they could find it.

Describe the solution you'd like

A short mention on both the Password and Authority records pages regarding where a paper password can be found, once a paper has been submitted. Currently a paper password is received in the confirmation e-mail of a submitted article.

Describe alternatives you've considered

There really are no better alternatives. This is very simple to implement, not very time consuming and the best option in terms of accessibility. I don't think anyone wants to spend the time to make a video on this?

Additional context

Some authors are not aware of the possibility of linking the arXiv accounts of other authors to a paper, so they do not pay attention to the part of the e-mail that tells the paper password, when it is first received. This is how I ended up looking for this information.

For Later - Reorg pages in Help

The Help pages have 80+ pages in the root directory. They should all be reorganized into a small set of main folders like
Submit
Read/Find
Policies
API and Bulk Data Users

When the reorg happens, the redirects for the pages need to be tracked.
The links inside all pages that refer to the moved page also need to be updated.

Search by date missing from the API docs

Describe the bug
Already in 2009 there was an undocumented search by date: https://groups.google.com/g/arxiv-api/c/mAFYT2VRpK0/m/hGTScrUUndwJ

I believe it is still not documented.

To Reproduce

Check the query construction part of the API user docs for the mention of a search by submission date. Observe that the search by submission date isn't mentioned.

Expected behavior
Search by submission date is documented in that section.

images not appearing at https://info.arxiv.org/help/withdraw.html

pinning this to look into later

Incomplete rreplacement documentation

In https://arxiv.org/help/replace it says "The exceptions to this rule are the addition of journal reference and DOI information." One FAQ we have in LHCb is whether adding a report number triggers a new version. It turns out it does not, but regularly users point to this page to back up the opposite argument. Could you please explicitly write that new report numbers do not trigger new versions? Thanks. Patrick

license images not displayed do to wrong location

Describe the bug
currently, when visiting https://arxiv.org/help/license , no license images are displayed

To Reproduce
Steps to reproduce the behavior:

1. Go to 'https://arxiv.org/help/license'
2. Scroll down to 'Licenses available'
3. See error

Expected behavior
The license images should be displayed.

Screenshots

Search by date missing from the API docs

Describe the bug
A clear and concise description of what the bug is.

To Reproduce
Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: [e.g. iOS]
• Browser [e.g. chrome, safari]
• Version [e.g. 22]

Smartphone (please complete the following information):

• Device: [e.g. iPhone6]
• OS: [e.g. iOS8.1]
• Browser [e.g. stock browser, safari]
• Version [e.g. 22]

Additional context
Add any other context about the problem here.

Left Nav not displaying as expected from SUMMARY.md config

The source/SUMMARY.md content that Alison and I updated is different that what is getting deployed.
What we see in the deployment is a list of the /source/about/people pages
What we set in the source/SUMMARY.md config is
``
- about/people/index.md
- about/governance.md
- about/membership.md
- about/funding.md
- about/reports/index.md
- about/accessibility_research_report.html
- [arXiv Blog] (https://blog.arxiv.org/)

``

setup pretty subheadings in navigation

Currently the mkdocs navigation appears to display folders in Camel Case.
The folders in legacy were not written with correct case so those could be corrected.
Example /help/oa to /help/OA
The display in mkdocs would need to be configured to preserve the as written folder case
Example
OA would appear as OA instead of currently what happens is the legacy written folder "oa" is displayed as "Oa"

Migrate remaining content

Michelle worked on migrating html pages in the /help/ folder.
There are some non-html content (ex /hypertex/) and some content in '/' that the admins can migrate once the '/help/' directory is in place.

Content tracking is at
https://docs.google.com/spreadsheets/d/1eSO07fr2EXmPTNJMN4o9mndPMN3cMHa1JUQIPfSfVkE/edit#gid=0

searching the source of a graph: "ML + AI arXiv papers per month", someone is using this but does not show the original source of the graph.

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

NEW

Describe the bug
A clear and concise description of what the bug is.

To Reproduce
Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: [e.g. iOS]
• Browser [e.g. chrome, safari]
• Version [e.g. 22]

Smartphone (please complete the following information):

• Device: [e.g. iPhone6]
• OS: [e.g. iOS8.1]
• Browser [e.g. stock browser, safari]
• Version [e.g. 22]

Additional context
Add any other context about the problem here.

create /site/pages/help/ and move Michelle's work to that folder.

When this work started we weren't sure about the directory structure. It turns out all the content in the /pages/ folder, including all the sub-folders, should be in /pages/help/. I'll need help with that as I'm not that fluent in github.

2020 update typo

In 2019, the repository received 1,639,224 new submissions, a 10% increase from 2018
^ this and the % after looks like grand total rather than annual total

typo on author page

Describe the bug
On the author page the third dot item in the preflight check box reads:
"Common errors that slow down announcement include mission files or bibliography."
It should read:
"Common errors that slow down announcement include missing files or bibliography."

Desktop (please complete the following information):

• OS: MACOS 13.0
• Browser: Firefox 115.0.3

"usage stats" link broken on about page

On this page
https://info.arxiv.org/about/index.html

the link for "Usage Stats" goes to https://stats/main

I think that should be https://arxiv.org/stats/main

the link to the "what is bibex?" from every single abs page is busted

Describe the bug
Going to https://labs.arxiv.org/projects/bibexplorer results in a 404

To Reproduce
Steps to reproduce the behavior:

1. Go to https://labs.arxiv.org/projects/bibexplorer
2. See the 404
3. ???
4. No profit.

Expected behavior
Not a 404. Preferably a page with content.

Additional context
d'oh

check public pages in arxiv-submit

When Jim first looked at migrating static pages he just looked at arxiv-httpd-htdocs
It turns out there are also public pages in arxiv-submit
ex
/user/tex_accents

Need to go through looking for other arxiv-submit static pages to move over

Need credit for licensing

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

404 ?

Describe the bug
A clear and concise description of what the bug is.

To Reproduce
Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: [e.g. iOS]
• Browser [e.g. chrome, safari]
• Version [e.g. 22]

Smartphone (please complete the following information):

• Device: [e.g. iPhone6]
• OS: [e.g. iOS8.1]
• Browser [e.g. stock browser, safari]
• Version [e.g. 22]

Additional context
Add any other context about the problem here.

Description for the `stat` classification is missing

Describe the bug
There is no information for the stat classification.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://info.arxiv.org/help/stat/index.html
2. See missing page 404 - Not found.

Expected behavior
Information about the stat classification, and what does it mean each subclass: Applications; Computation; Machine Learning; Methodology; Other Statistics; Statistics Theory

Screenshots

Desktop (please complete the following information):

• OS: MacOS
• Browser Firefox
• Version 102

Additional context
NA